Files
vastsa 381a539c92 fix: resolve OSS chunk cleanup and legacy download issues
Use compatible S3 checksum settings, retry failed cleanup without reusing completed uploads, and include legacy attachment filenames. Correct admin-page URLs in both documentation languages.

Refs #556, #531, #502
2026-10-27 16:08:35 +08:00

432 lines
12 KiB
Markdown

# Admin Panel
FileCodeBox provides a fully-featured admin panel that allows administrators to conveniently manage files, view system status, and modify configurations. This document introduces the various features and usage of the admin panel.
## Accessing the Admin Panel
<p align="center">
<img src="/screenshots/login.webp" alt="Admin login" width="640" />
</p>
### Login Method
The admin panel is located at `/#/admin` (a frontend hash route). Access method:
1. On first run, set the admin password on the setup page
2. Visit `http://your-domain.com/#/admin` in your browser
3. Enter the admin password (the value of the `admin_token` configuration)
4. Click the login button
::: tip Tip
The setup page is shown automatically while the system is uninitialized. Complete setup before exposing a production service to the public internet.
:::
### Show Admin Entry
By default, the admin panel entry is not shown on the homepage. You can control whether to show it via configuration:
| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `show_admin_addr` | int | `0` | Show admin entry on homepage (1=show, 0=hide) |
::: warning Security Recommendation
For public services, keep `show_admin_addr` at `0` and access the admin panel via `/#/admin`. Hiding the link is not access control; a strong password is still required.
:::
### Authentication Mechanism
The admin panel uses JWT (JSON Web Token) for authentication:
1. After successful login, the server returns a Token containing admin identity
2. Subsequent requests carry the Token via `Authorization: Bearer <token>` header
3. Token is used to verify admin identity, ensuring only authorized users can access admin functions
## Dashboard
<p align="center">
<img src="/screenshots/dashboard.webp" alt="Dashboard" width="860" />
</p>
After logging in, you first see the dashboard page, which displays the overall system status.
### Statistics
The dashboard displays the following key metrics:
| Metric | Description |
|--------|-------------|
| **Total Files** (`totalFiles`) | Total number of files stored in the system |
| **Storage Used** (`storageUsed`) | Total storage space occupied by all files (bytes) |
| **System Uptime** (`sysUptime`) | Time when the system was first started |
| **Yesterday's Uploads** (`yesterdayCount`) | Number of files uploaded yesterday |
| **Yesterday's Upload Size** (`yesterdaySize`) | Total size of files uploaded yesterday (bytes) |
| **Today's Uploads** (`todayCount`) | Number of files uploaded today so far |
| **Today's Upload Size** (`todaySize`) | Total size of files uploaded today (bytes) |
### Metric Notes
- **Total Files**: Includes all unexpired files and text shares
- **Storage Used**: Shows actual storage space occupied by files, excluding database and other system files
- **Yesterday/Today Statistics**: Calculated based on file creation time, useful for understanding system usage trends
::: tip Tip
Storage usage is displayed in bytes. For example, `10485760` represents approximately 10MB.
:::
## File Management
<p align="center">
<img src="/screenshots/files.webp" alt="File management" width="860" />
</p>
### File List
The file management page displays all shared files in the system, supporting pagination and search.
**List information includes:**
- File ID
- Extraction code (code)
- Filename prefix (prefix)
- File extension (suffix)
- File size
- Creation time
- Expiration time
- Remaining download count
### Search Files
Use the search function to quickly find specific files:
1. Enter keywords in the search box
2. System performs fuzzy matching based on filename prefix (prefix)
3. Search results update in real-time
**Search examples:**
- Enter `report` to find all files with "report" in the filename
- Enter `.pdf` to find all PDF files (if the filename contains this string)
### Pagination
The file list supports paginated display:
| Parameter | Default | Description |
|-----------|---------|-------------|
| `page` | `1` | Current page number |
| `size` | `10` | Items per page |
### Delete Files
Administrators can delete any file:
1. Find the file to delete in the file list
2. Click the delete button
3. Confirm the delete operation
::: danger Warning
Delete operations are irreversible! Files will be permanently deleted from the storage backend, and database records will also be removed.
:::
**Delete process:**
1. System first deletes the actual file from the storage backend (local/S3/OneDrive, etc.)
2. Then deletes the file record from the database
3. After deletion, the corresponding extraction code becomes invalid
### Download Files
Administrators can directly download any file:
1. Find the target file in the file list
2. Click the download button
3. File will be downloaded via browser
For text shares, the system returns text content directly instead of downloading a file.
### Modify File Information
Administrators can modify some information of shared files:
| Modifiable Field | Description |
|------------------|-------------|
| `code` | Extraction code (must be unique, cannot duplicate other files) |
| `prefix` | Filename prefix |
| `suffix` | File extension |
| `expired_at` | Expiration time |
| `expired_count` | Remaining download count |
**Modify extraction code:**
```
Original code: abc123
New code: myfile2024
```
::: warning Note
When modifying extraction codes, the system checks if the new code is already in use. If an identical extraction code exists, the modification will fail.
:::
## Local File Management
In addition to managing shared files, the admin panel has a Local Share page for browsing `data/local` (including subfolders) and minting extract codes.
Mount a NAS share at `/app/data/local` to generate extract codes for files already on disk, without downloading and re-uploading them.
```yaml
volumes:
- fcb-data:/app/data:rw
# Read-only NAS share for admin browsing and extract-code generation
- /volume1/share:/app/data/local:ro
```
### View Local Files
The Local Share page supports nested folders. List API:
```
GET /admin/local/lists?path=movies
```
`path` is relative to `data/local`; leave it empty for the root. Response:
| Field | Description |
|------|------|
| `path` | Current directory |
| `parent` | Parent directory |
| `truncated` | Whether the listing was truncated |
| `items[].type` | `dir` or `file` |
| `items[].path` | Path relative to `data/local`, used as `filename` when sharing |
### Share Local Files
1. Open the target subfolder and pick a file
2. Set expiration method and value
3. Create an extract code
Sharing is a **zero-copy reference**: the file is not copied into `data/share` and does not count against storage quota. Expiring or deleting the share record **does not delete the original NAS file**.
**Share parameters:**
| Parameter | Description |
|-----------|-------------|
| `filename` | Path relative to `data/local`, e.g. `movies/a.mp4` |
| `expire_style` | Expiration method (day/hour/minute/forever/count) |
| `expire_value` | Expiration value (days/hours/minutes/download count) |
## System Settings
<p align="center">
<img src="/screenshots/settings.webp" alt="System settings" width="860" />
</p>
### View Configuration
On the system settings page, you can view the current values of all configuration items. Configuration items are grouped by category:
- Basic settings (site name, description, etc.)
- Upload settings (file size limits, rate limits, etc.)
- Storage settings (storage type, path, etc.)
- Theme settings (theme selection, opacity, etc.)
- Security settings (admin password, error limits, etc.)
### Modify Configuration
Administrators can modify most configurations through the admin panel:
1. Go to the system settings page
2. Find the configuration item to modify
3. Enter the new value
4. Click the save button
**Modifiable configuration items:**
| Category | Example Settings |
|----------|------------------|
| Basic Settings | `name`, `description`, `keywords`, `notify_title`, `notify_content` |
| Upload Settings | `upload_size`, `upload_minute`, `upload_count`, `open_upload`, `enable_chunk` |
| Expiration Settings | `expire_style`, `max_save_seconds` |
| Theme Settings | `themes_select`, `opacity`, `background` |
| Security Settings | `admin_token`, `show_admin_addr`, `error_minute`, `error_count` |
| Storage Settings | `file_storage`, `storage_path` and storage backend-specific configurations |
::: warning Note
- `admin_token` (admin password) cannot be set to empty
- `themes_choices` (theme list) cannot be modified through the admin panel
- After modifying storage settings, existing files will not be automatically migrated
:::
### Configuration Effect
Configuration changes take effect immediately without restarting the service. Configurations are saved in the database and persist after restart.
**Configuration storage location:**
- Database: `data/filecodebox.db`
- Table name: `keyvalue`
- Key name: `settings`
## API Endpoints
All admin panel functions are implemented through REST APIs. Here are the main endpoints:
### Authentication Endpoint
**Login**
```
POST /admin/login
Content-Type: application/json
{
"password": "your-admin-password"
}
```
Response:
```json
{
"code": 200,
"detail": {
"token": "eyJhbGciOiJIUzI1NiIs...",
"token_type": "Bearer"
}
}
```
### Dashboard Endpoint
**Get Statistics**
```
GET /admin/dashboard
Authorization: Bearer <token>
```
### File Management Endpoints
**Get File List**
```
GET /admin/file/list?page=1&size=10&keyword=
Authorization: Bearer <token>
```
**Delete File**
```
DELETE /admin/file/delete
Authorization: Bearer <token>
Content-Type: application/json
{
"id": 123
}
```
**Download File**
```
GET /admin/file/download?id=123
Authorization: Bearer <token>
```
**Modify File Information**
```
PATCH /admin/file/update
Authorization: Bearer <token>
Content-Type: application/json
{
"id": 123,
"code": "newcode",
"expired_at": "2024-12-31T23:59:59"
}
```
### Local File Endpoints
**Get Local File List**
```
GET /admin/local/lists?path=movies
Authorization: Bearer <token>
```
**Delete Local File**
```
DELETE /admin/local/delete
Authorization: Bearer <token>
Content-Type: application/json
{
"filename": "movies/example.txt"
}
```
**Share Local File**
```
POST /admin/local/share
Authorization: Bearer <token>
Content-Type: application/json
{
"filename": "movies/example.txt",
"expire_style": "day",
"expire_value": 7
}
```
### Configuration Endpoints
**Get Configuration**
```
GET /admin/config/get
Authorization: Bearer <token>
```
**Update Configuration**
```
PATCH /admin/config/update
Authorization: Bearer <token>
Content-Type: application/json
{
"admin_token": "new-password",
"upload_size": 52428800
}
```
## Common Issues
### Forgot Admin Password
If you forgot the admin password, you can reset it through the following methods:
1. Stop the FileCodeBox service
2. Open `data/filecodebox.db` using an SQLite tool
3. Query the record with `key='settings'` in the `keyvalue` table
4. Modify the `admin_token` value in the JSON
5. Restart the service
```sql
-- View current configuration
SELECT * FROM keyvalue WHERE key = 'settings';
-- Or delete configuration to restore default password
DELETE FROM keyvalue WHERE key = 'settings';
```
### File Deletion Failed
If an error occurs when deleting files, possible reasons:
1. **Storage backend connection failed**: Check if storage configuration is correct
2. **File no longer exists**: File may have been manually deleted
3. **Insufficient permissions**: Check write permissions for storage directory
### Configuration Changes Not Taking Effect
If configuration changes don't take effect:
1. Check if you clicked the save button
2. Refresh the page to see if configuration was saved
3. Check browser console for error messages
4. Confirm configuration value format is correct (e.g., don't enter strings for numeric types)
## Next Steps
- [Configuration Guide](/en/guide/configuration) - Learn detailed descriptions of all configuration options
- [Security Settings](/en/guide/security) - Learn how to enhance system security
- [Storage Configuration](/en/guide/storage) - Configure different storage backends