feat: 利用AI更新文档

2025-12-01 14:10:06 +08:00
parent 859a51516a
commit a3f1fd6a4c
20 changed files with 4598 additions and 313 deletions
@@ -0,0 +1,380 @@
+# File Upload
+
+FileCodeBox provides multiple flexible file upload methods, supporting both regular upload and chunked upload to meet different scenario requirements.
+
+## Upload Methods
+
+FileCodeBox supports the following upload methods:
+
+### Drag and Drop Upload
+
+Drag files directly to the upload area to start uploading. This is the most convenient upload method.
+
+1. Open the FileCodeBox homepage
+2. Drag files from your file manager to the upload area
+3. Release the mouse, file upload begins
+4. Get the extraction code after upload completes
+
+::: tip Tip
+Drag and drop upload supports dragging multiple files simultaneously (depending on theme support).
+:::
+
+### Click Upload
+
+Click the upload area to select files through the system file picker.
+
+1. Click the "Select File" button in the upload area
+2. Select the file to upload in the popup file picker
+3. File upload begins after confirming selection
+4. Get the extraction code after upload completes
+
+### Paste Upload
+
+Supports pasting images directly from clipboard for upload (supported by some themes).
+
+1. Copy an image to clipboard (screenshot or copy image)
+2. Use `Ctrl+V` (Windows/Linux) or `Cmd+V` (macOS) to paste in the upload area
+3. Image upload starts automatically
+4. Get the extraction code after upload completes
+
+::: warning Note
+Paste upload only supports image formats, not other file types. Specific support depends on the theme being used.
+:::
+
+## File Size Limits
+
+### Default Limits
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `uploadSize` | 10MB | Maximum single file upload size |
+
+### Modify Upload Limits
+
+Administrators can modify upload size limits through the admin panel or configuration file:
+
+```python
+# Set maximum upload size to 100MB
+uploadSize = 104857600  # 100 * 1024 * 1024
+```
+
+::: info Note
+`uploadSize` is in bytes. Common conversions:
+- 10MB = 10485760
+- 50MB = 52428800
+- 100MB = 104857600
+- 500MB = 524288000
+- 1GB = 1073741824
+:::
+
+### Exceeding Limit Handling
+
+When an uploaded file exceeds the size limit, the system returns a 403 error:
+
+```json
+{
+  "detail": "Size exceeds limit, maximum is 10.00 MB"
+}
+```
+
+## Regular Upload API
+
+### File Upload Endpoint
+
+**POST** `/share/file/`
+
+Content-Type: `multipart/form-data`
+
+**Request parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `file` | file | Yes | File to upload |
+| `expire_value` | int | No | Expiration value, default 1 |
+| `expire_style` | string | No | Expiration method, default `day` |
+
+**Expiration method options:**
+
+| Value | Description |
+|-------|-------------|
+| `day` | Expire by days |
+| `hour` | Expire by hours |
+| `minute` | Expire by minutes |
+| `forever` | Never expire |
+| `count` | Expire by download count |
+
+**Response example:**
+
+```json
+{
+  "code": 200,
+  "detail": {
+    "code": "654321",
+    "name": "example.pdf"
+  }
+}
+```
+
+**cURL example:**
+
+```bash
+curl -X POST "http://localhost:12345/share/file/" \
+  -F "file=@/path/to/file.pdf" \
+  -F "expire_value=7" \
+  -F "expire_style=day"
+```
+
+
+## Chunked Upload API
+
+For large files, FileCodeBox supports chunked upload functionality. Chunked upload splits large files into multiple small chunks for separate uploading, supporting resume capability.
+
+::: warning Prerequisite
+Chunked upload functionality requires administrator enablement: `enableChunk=1`
+:::
+
+### Chunked Upload Flow
+
+```
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│  Initialize │ ──▶ │Upload Chunks│ ──▶ │  Complete   │
+│   /init/    │     │  /chunk/    │     │ /complete/  │
+└─────────────┘     └─────────────┘     └─────────────┘
+                          │
+                          ▼
+                    ┌───────────┐
+                    │   Loop    │
+                    │each chunk │
+                    └───────────┘
+```
+
+### 1. Initialize Upload
+
+**POST** `/chunk/upload/init/`
+
+**Request parameters:**
+
+```json
+{
+  "file_name": "large_file.zip",
+  "file_size": 104857600,
+  "chunk_size": 5242880,
+  "file_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+}
+```
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `file_name` | string | Yes | - | Filename |
+| `file_size` | int | Yes | - | Total file size (bytes) |
+| `chunk_size` | int | No | 5MB | Chunk size (bytes) |
+| `file_hash` | string | Yes | - | SHA256 hash of the file |
+
+**Response example:**
+
+```json
+{
+  "code": 200,
+  "detail": {
+    "existed": false,
+    "upload_id": "abc123def456789",
+    "chunk_size": 5242880,
+    "total_chunks": 20,
+    "uploaded_chunks": []
+  }
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `existed` | Whether file already exists (instant upload) |
+| `upload_id` | Upload session ID |
+| `chunk_size` | Chunk size |
+| `total_chunks` | Total number of chunks |
+| `uploaded_chunks` | List of already uploaded chunk indices |
+
+### 2. Upload Chunk
+
+**POST** `/chunk/upload/chunk/{upload_id}/{chunk_index}`
+
+**Path parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| `upload_id` | Upload session ID returned during initialization |
+| `chunk_index` | Chunk index, starting from 0 |
+
+**Request body:**
+
+Content-Type: `multipart/form-data`
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `chunk` | file | Chunk data |
+
+**Response example:**
+
+```json
+{
+  "code": 200,
+  "detail": {
+    "chunk_hash": "a1b2c3d4e5f6..."
+  }
+}
+```
+
+**cURL example:**
+
+```bash
+# Upload first chunk (index 0)
+curl -X POST "http://localhost:12345/chunk/upload/chunk/abc123def456789/0" \
+  -F "chunk=@/path/to/chunk_0"
+```
+
+### 3. Complete Upload
+
+**POST** `/chunk/upload/complete/{upload_id}`
+
+**Path parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| `upload_id` | Upload session ID |
+
+**Request parameters:**
+
+```json
+{
+  "expire_value": 7,
+  "expire_style": "day"
+}
+```
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `expire_value` | int | Yes | Expiration value |
+| `expire_style` | string | Yes | Expiration method |
+
+**Response example:**
+
+```json
+{
+  "code": 200,
+  "detail": {
+    "code": "789012",
+    "name": "large_file.zip"
+  }
+}
+```
+
+### Resume Upload
+
+Chunked upload supports resume functionality. When upload is interrupted:
+
+1. Call the initialization endpoint again with the same `file_hash`
+2. Server returns `uploaded_chunks` list containing already uploaded chunk indices
+3. Client only needs to upload chunks not in the list
+4. Call the complete endpoint after all chunks are uploaded
+
+**Example flow:**
+
+```javascript
+// 1. Initialize upload
+const initResponse = await fetch('/chunk/upload/init/', {
+  method: 'POST',
+  body: JSON.stringify({
+    file_name: 'large_file.zip',
+    file_size: fileSize,
+    chunk_size: 5 * 1024 * 1024,
+    file_hash: fileHash
+  })
+});
+const { upload_id, uploaded_chunks, total_chunks } = await initResponse.json();
+
+// 2. Upload incomplete chunks
+for (let i = 0; i < total_chunks; i++) {
+  if (!uploaded_chunks.includes(i)) {
+    const chunk = file.slice(i * chunkSize, (i + 1) * chunkSize);
+    await fetch(`/chunk/upload/chunk/${upload_id}/${i}`, {
+      method: 'POST',
+      body: chunk
+    });
+  }
+}
+
+// 3. Complete upload
+await fetch(`/chunk/upload/complete/${upload_id}`, {
+  method: 'POST',
+  body: JSON.stringify({
+    expire_value: 7,
+    expire_style: 'day'
+  })
+});
+```
+
+## Error Handling
+
+### Common Errors
+
+| HTTP Status | Error Message | Cause | Solution |
+|-------------|---------------|-------|----------|
+| 403 | Size exceeds limit | File exceeds `uploadSize` limit | Reduce file size or contact administrator to adjust limit |
+| 403 | Upload rate limit | Exceeded IP upload rate limit | Wait for limit time window before retrying |
+| 400 | Invalid expiration type | `expire_style` value not in allowed list | Use a valid expiration method |
+| 404 | Upload session not found | `upload_id` invalid or expired | Re-initialize upload |
+| 400 | Invalid chunk index | `chunk_index` out of range | Check if chunk index is correct |
+| 400 | Incomplete chunks | Chunk count insufficient when completing upload | Ensure all chunks are uploaded |
+
+### Rate Limiting
+
+The system has rate limits on upload operations to prevent abuse:
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `uploadMinute` | 1 | Limit time window (minutes) |
+| `uploadCount` | 10 | Maximum uploads within time window |
+
+When rate limit is exceeded, you need to wait for the time window to pass before continuing uploads.
+
+### Error Response Format
+
+```json
+{
+  "detail": "Error message description"
+}
+```
+
+## Upload Configuration
+
+### Related Settings
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `openUpload` | int | 1 | Enable upload (1=enabled, 0=disabled) |
+| `uploadSize` | int | 10485760 | Maximum upload size (bytes) |
+| `enableChunk` | int | 0 | Enable chunked upload (1=enabled, 0=disabled) |
+| `uploadMinute` | int | 1 | Upload rate limit time window (minutes) |
+| `uploadCount` | int | 10 | Maximum uploads within time window |
+| `expireStyle` | list | ["day","hour","minute","forever","count"] | Allowed expiration methods |
+
+### Configuration Example
+
+```python
+# Allow 100MB file uploads, enable chunked upload
+uploadSize = 104857600
+enableChunk = 1
+
+# Relax upload rate limit: max 50 uploads per 5 minutes
+uploadMinute = 5
+uploadCount = 50
+
+# Only allow expiration by days and count
+expireStyle = ["day", "count"]
+```
+
+## Next Steps
+
+- [File Sharing](/en/guide/share) - Learn the complete sharing process
+- [Configuration Guide](/en/guide/configuration) - Learn about all configuration options
+- [Storage Configuration](/en/guide/storage) - Learn about file storage methods
+- [Security Settings](/en/guide/security) - Learn about security-related configurations