feat: 利用AI更新文档

2025-12-01 14:10:06 +08:00
parent d7200f6b9b
commit a20a0beb79
20 changed files with 4598 additions and 313 deletions
@@ -0,0 +1,413 @@
+# 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
+
+### Login Method
+
+The admin panel is located at the `/admin` path. Access method:
+
+1. Visit `http://your-domain.com/admin` in your browser
+2. Enter the admin password (the value of the `admin_token` configuration)
+3. Click the login button
+
+::: tip Tip
+The default admin password is `FileCodeBox2023`. Be sure to change this password in production environments. See [Security Settings](/en/guide/security) for details.
+:::
+
+### 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 |
+|---------|------|---------|-------------|
+| `showAdminAddr` | int | `0` | Show admin entry on homepage (1=show, 0=hide) |
+
+::: warning Security Recommendation
+For public services, it's recommended to keep `showAdminAddr` at `0` and access the admin panel directly via the `/admin` path to reduce the risk of malicious scanning.
+:::
+
+### 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
+
+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
+
+### 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 also provides local file management functionality for managing files in the `data/local` directory.
+
+### View Local Files
+
+The local file list displays all files in the `data/local` directory:
+
+| Information | Description |
+|-------------|-------------|
+| Filename | Complete filename |
+| Creation Time | File creation time |
+| File Size | File size (bytes) |
+
+### Share Local Files
+
+You can quickly share local files:
+
+1. Select the file to share in the local file list
+2. Set expiration method and value
+3. Click the share button
+4. System generates extraction code
+
+**Share parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| `filename` | Filename to share |
+| `expire_style` | Expiration method (day/hour/minute/forever/count) |
+| `expire_value` | Expiration value (days/hours/minutes/download count) |
+
+### Delete Local Files
+
+You can delete files in the `data/local` directory:
+
+1. Find the file to delete in the local file list
+2. Click the delete button
+3. Confirm deletion
+
+::: tip Use Cases
+Local file management is useful for:
+- Sharing files after batch uploading to the server
+- Managing files uploaded to the server through other means
+- Cleaning up unnecessary local files
+:::
+
+## System Settings
+
+### 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 | `uploadSize`, `uploadMinute`, `uploadCount`, `openUpload`, `enableChunk` |
+| Expiration Settings | `expireStyle`, `max_save_seconds` |
+| Theme Settings | `themesSelect`, `opacity`, `background` |
+| Security Settings | `admin_token`, `showAdminAddr`, `errorMinute`, `errorCount` |
+| Storage Settings | `file_storage`, `storage_path` and storage backend-specific configurations |
+
+::: warning Note
+- `admin_token` (admin password) cannot be set to empty
+- `themesChoices` (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
+Authorization: Bearer <token>
+```
+
+**Delete Local File**
+```
+DELETE /admin/local/delete
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{
+    "filename": "example.txt"
+}
+```
+
+**Share Local File**
+```
+POST /admin/local/share
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{
+    "filename": "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",
+    "uploadSize": 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