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