save code

python/DEPLOYMENT.md

@@ -0,0 +1,133 @@
+# Face SDK Web 部署说明
+
+本文说明如何在服务器或本机长期运行 **Face SDK Web**（FastAPI + 静态前端）。开发与接口文字说明见根目录 [README.md](./README.md)。
+
+---
+
+## API 文档是否已经写好？
+
+有两层：
+
+| 类型 | 说明 |
+|------|------|
+| **交互式文档（推荐联调）** | 服务启动后由 FastAPI **自动生成**：浏览器打开 **`/docs`**（Swagger UI）、**`/redoc`**（ReDoc），可直接试请求。机器可读的模式在 **`/openapi.json`**。 |
+| **文字说明** | [README.md](./README.md) 的「API」一节描述了 `GET /health`、`GET /effects`、`POST /render` 的请求与响应；与代码保持一致即可。 |
+
+生产环境若不希望对外暴露 Swagger，应在网关层禁止访问 `/docs`、`/redoc`、`/openapi.json`（见下文反向代理示例）。
+
+---
+
+## 运行环境
+
+- **Python**：3.10～3.12（MediaPipe 当前不支持 3.13）。
+- **CPU**：无需 GPU；推理与渲染在 CPU 上完成。
+- **系统**：Windows / Linux / macOS 均可；生产常见为 Linux。
+
+---
+
+## 部署时需携带的文件
+
+在 **`python/`** 目录下至少包含：
+
+- `requirements.txt`
+- `server/` 整个包，尤其：
+  - `server/main.py` 及依赖的 `.py`
+  - `server/assets/`（含 `face_picture_3dmax.obj`；`face_landmarker.task` 按 README 可选）
+  - `server/effects/`（`<id>.png` 效果贴图）
+  - `server/static/`（前端 `index.html` 及静态资源）
+
+工作目录应为 **`python/`**（即包含 `server` 包的那一层），以便 `uvicorn server.main:app` 能正确导入。
+
+---
+
+## 安装依赖
+
+```bash
+cd /path/to/face_sdk/python
+python3 -m venv venv
+source venv/bin/activate          # Windows: .\venv\Scripts\Activate.ps1
+pip install --upgrade pip
+pip install -r requirements.txt
+```
+
+---
+
+## 启动方式
+
+### 开发 / 小规模使用
+
+```bash
+cd /path/to/face_sdk/python
+source venv/bin/activate
+uvicorn server.main:app --host 0.0.0.0 --port 8000
+```
+
+- 根路径 **`/`**：返回 `server/static/index.html`
+- **`/static/*`**：静态文件
+- 日志出现 **`Application startup complete.`** 即就绪
+
+### 生产建议（Linux）
+
+- 使用 **进程管理器**（systemd、supervisor）或容器，保证崩溃自动拉起。
+- 前面挂 **Nginx / Caddy / 云 LB**，统一 TLS 与限流。
+- **Worker 数量**：README「已知限制」中说明 MediaPipe 检测在应用内通过锁串行化；单进程多 worker **不会**线性提升同一实例内的 GPU 式并行，且可能重复加载模型占内存。更高并发可采用：**多实例（每实例单 worker）+ 负载均衡**，或前置队列削峰。
+
+示例（单 worker，监听本机 127.0.0.1，由 Nginx 对外）：
+
+```bash
+uvicorn server.main:app --host 127.0.0.1 --port 8000 --workers 1
+```
+
+---
+
+## 反向代理示例（Nginx）
+
+将 HTTPS 流量转到本机 Uvicorn，并可选屏蔽文档路径：
+
+```nginx
+server {
+    listen 443 ssl;
+    server_name your.domain.example;
+
+    # ssl_certificate / ssl_certificate_key ...
+
+    location / {
+        proxy_pass http://127.0.0.1:8000;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        client_max_body_size 25m;   # 略高于应用内图片上限（默认 20MB）
+    }
+
+    # 生产可注释掉以下整块，禁止外网访问 API 探索页
+    # location ~ ^/(docs|redoc|openapi\.json)$ {
+    #     deny all;
+    # }
+}
+```
+
+---
+
+## 健康检查
+
+负载均衡或编排（如 K8s）可使用：
+
+- **`GET /health`** — 成功返回 `200`，JSON：`{"ok": true}`
+
+---
+
+## 防火墙与安全
+
+- 若不经反向代理，直接监听 `0.0.0.0`，需在主机防火墙与安全组中 **仅开放必要端口**。
+- **`POST /render`** 接收用户上传文件，务必通过 HTTPS、合理 **`client_max_body_size`** / 限流，防止滥用。
+
+---
+
+## 常见问题
+
+- **端口被占用**：更换 `--port` 或结束占用进程后再启动。
+- **找不到模型或 OBJ**：确认 `server/assets/` 与 `server/effects/` 已随代码一并部署，且工作目录为 `python/`。
+
+更多行为与性能说明见 [README.md](./README.md)「已知限制」。