docs: 更新API文档，添加临时文件上传API和临时发言说明

2026-05-27 21:19:35 +08:00
parent 6f0eb5f4a5
commit 8bf9ae8b6c
1 changed files with 113 additions and 51 deletions
--- a/README.md
+++ b/README.md
@@ -1588,9 +1588,11 @@ sudo systemctl restart gunicorn

 ---

+---
+
 ## API接口文档

-系统提供RESTful API接口，用于外部客户端提交汇总记录。
+系统提供RESTful API接口，支持外部客户端提交汇总记录和临时文件。

 ### 1. 汇总记录提交API

@@ -1607,6 +1609,7 @@ sudo systemctl restart gunicorn
 | 参数名 | 类型 | 必填 | 说明 |
 |-------|------|------|------|
 | content | string | 是 | 汇总记录内容，最大长度不限 |
+| source | string | 否 | 来源，自动获取客户端主机名和IP |

 #### 响应格式

@@ -1639,7 +1642,7 @@ import requests

 url = "http://your-server/api/v1/summary/submit/"
 data = {
-    "content": "监控报告：系统运行正常，CPU使用率15%，内存使用率42%"
+    "content": "监控报告：系统运行正常"
 }

 response = requests.post(url, data=data)
@@ -1647,50 +1650,6 @@ result = response.json()
 print(result)
 ```

-#### 客户端自动提交示例
-
-创建一个Python脚本用于自动提交系统监控数据：
-
-```python
-#!/usr/bin/env python3
-# submit_summary.py
-
-import socket
-import psutil
-import requests
-from datetime import datetime
-
-def get_system_info():
-    """获取系统基本信息"""
-    cpu_percent = psutil.cpu_percent(interval=1)
-    memory = psutil.virtual_memory()
-    disk = psutil.disk_usage('/')
-    return {
-        'cpu': cpu_percent,
-        'memory': memory.percent,
-        'disk': disk.percent
-    }
-
-def submit_summary(content):
-    """提交汇总记录到家庭日报系统"""
-    url = "http://your-server/api/v1/summary/submit/"
-    try:
-        response = requests.post(url, data={'content': content}, timeout=10)
-        result = response.json()
-        if result['success']:
-            print(f"提交成功，记录ID: {result['id']}")
-        else:
-            print(f"提交失败: {result['message']}")
-    except Exception as e:
-        print(f"请求异常: {str(e)}")
-
-if __name__ == "__main__":
-    info = get_system_info()
-    timestamp = datetime.now().strftime('%Y-%m-%d %H:%M:%S')
-    content = f"[系统监控 {timestamp}] CPU使用率: {info['cpu']}%, 内存使用率: {info['memory']}%, 磁盘使用率: {info['disk']}%"
-    submit_summary(content)
-```
-
 #### 注意事项

 1. **数据验证**：API仅接受以下条件的记录：
@@ -1702,11 +1661,103 @@ if __name__ == "__main__":

 3. **日期自动设置**：记录日期自动设置为提交时的日期。

-4. **错误处理**：如果分类或发言人不存在，API会返回错误信息。
+---

-### 2. 初始化必需数据
+### 2. 临时文件上传API

-在使用API提交功能前，需要确保数据库中存在以下数据：
+用于上传临时文件到公开内容，支持1小时/1天/7天过期自动删除。
+
+#### 请求信息
+
+- **URL**: `/api/v1/temp-upload/`
+- **方法**: `POST`
+- **Content-Type**: `multipart/form-data`
+- **文件大小限制**: 500MB
+
+#### 请求参数
+
+| 参数名 | 类型 | 必填 | 说明 |
+|-------|------|------|------|
+| title | string | 是 | 文件标题 |
+| file | file | 是 | 上传的文件，最大500MB |
+| expire_type | string | 是 | 过期时间：`expire_1h`(1小时) / `expire_1d`(1天) / `expire_7d`(7天) |
+
+#### 响应格式
+
+**成功响应** (HTTP 200):
+```json
+{
+    "success": true,
+    "message": "上传成功",
+    "id": 1,
+    "file_url": "http://your-server/media/public_files/xxx.pdf",
+    "file_name": "document.pdf",
+    "file_size": 1048576,
+    "expire_at": "2026-05-25T18:30:00Z",
+    "expire_type": "expire_1d"
+}
+```
+
+**失败响应** (HTTP 400/500):
+```json
+{
+    "success": false,
+    "message": "错误信息描述"
+}
+```
+
+#### 调用示例
+
+```bash
+# 使用 curl 上传文件
+curl -X POST http://your-server/api/v1/temp-upload/ \
+  -F "file=@document.pdf" \
+  -F "title=测试文件" \
+  -F "expire_type=expire_1d"
+
+# Python requests 调用示例
+import requests
+
+url = "http://your-server/api/v1/temp-upload/"
+files = {'file': open('document.pdf', 'rb')}
+data = {
+    'title': '测试文件',
+    'expire_type': 'expire_1d'
+}
+
+response = requests.post(url, files=files, data=data)
+result = response.json()
+print(result)
+```
+
+---
+
+### 3. 临时发言（页面表单）
+
+在公开内容页面 `/public/` 提供临时留言功能。
+
+#### 功能说明
+
+- 用户名：可选，最大20字节
+- 内容：必填，最大1000字节
+- 留言保留时间：10分钟
+- 显示：用户名（可选）、内容、时间、来源IP
+
+#### 提交方式
+
+在 `/public/` 页面直接填写表单提交，无需API调用。
+
+#### 显示规则
+
+- 只显示10分钟内的留言
+- 过期后自动从页面移除
+- 后台定时任务定期清理过期数据
+
+---
+
+### 4. 初始化必需数据
+
+在使用API提交汇总记录前，需要确保数据库中存在以下数据：

 #### 方法一：Django Shell初始化

@@ -1738,7 +1789,9 @@ print('初始化完成')
 2. 在 **汇总分类** 中添加名为"定期"的分类
 3. 在 **家庭成员** 中添加名为"机器人"的成员

-### 3. 常见问题排查
+---
+
+### 5. 常见问题排查

 #### 问题1：提交返回"分类 '定期' 不存在"

@@ -1748,7 +1801,7 @@ print('初始化完成')

 **解决方法**：在数据库中创建该发言人（见上方初始化方法）

-#### 问题3：提交返回"内容不能为空"
+#### 问题3：上传返回"内容不能为空"

 **解决方法**：确保请求中包含 `content` 参数且不为空

@@ -1756,6 +1809,15 @@ print('初始化完成')

 **解决方法**：确认使用的是POST方法，不是GET方法

+#### 问题5：文件上传失败（413 Request Entity Too Large）
+
+**解决方法**：检查nginx配置中的 `client_max_body_size` 是否大于500m
+
+```nginx
+# 在 /etc/nginx/sites-enabled/diary_family 中添加
+client_max_body_size 500m;
+```
+
 ## Fail2ban 登录保护配置

 为了防止暴力破解登录密码，系统集成了 Fail2ban 自动封禁功能。当用户在短时间内多次登录失败时，其 IP 地址将被自动封禁。