mirror of
https://github.com/vastsa/FileCodeBox.git
synced 2026-11-22 06:57:56 +08:00
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
432 lines
12 KiB
Markdown
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
|