Face SDK Web 部署说明

本文说明如何在服务器或本机长期运行 Face SDK Web（FastAPI + 静态前端）。开发与接口文字说明见根目录 README.md。

API 文档是否已经写好？

有两层：

类型	说明
交互式文档（推荐联调）	服务启动后由 FastAPI 自动生成：浏览器打开 `/docs`（Swagger UI）、`/redoc`（ReDoc），可直接试请求。机器可读的模式在 `/openapi.json`。
文字说明	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 能正确导入。

安装依赖

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

启动方式

开发 / 小规模使用

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 对外）：

uvicorn server.main:app --host 127.0.0.1 --port 8000 --workers 1

反向代理示例（Nginx）

将 HTTPS 流量转到本机 Uvicorn，并可选屏蔽文档路径：

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「已知限制」。

4.2 KiB Raw Blame History Unescape Escape