134 lines
4.2 KiB
Markdown
134 lines
4.2 KiB
Markdown
# 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)「已知限制」。
|