# Clover 客户交付运行说明

Clover 是北哥小红书产品内容生产系统，包含：

- `backend/`：FastAPI + Celery + MySQL + MongoDB + Redis
- `frontend/`：Next.js 运营端
- `docker-compose.prod.yml`：客户交付部署入口，数据库端口不暴露到宿主机

## 交付前必做

1. 复制 `.env.example` 为 `.env`，填入客户环境专属密钥和域名。
2. 生成新的 `FERNET_KEY`、`JWT_SECRET`、数据库密码，不复用开发环境值。
3. 同域 nginx 部署时 `NEXT_PUBLIC_API_BASE_URL` 和 `NEXT_PUBLIC_SSE_BASE_URL` 保持空；前后端分域时填公网 API 域名，修改后必须重新 build 前端镜像。
4. 设置 `CORS_ALLOW_ORIGINS` 为客户前端域名，多个域名用英文逗号分隔。
5. 交付包不要包含任何真实 `.env`、`.env.bak`、`node_modules`、`.next`、`verify_output`、截图或本地日志。

## 生产启动

HTTP 内测：

```bash
docker compose -f docker-compose.prod.yml --env-file .env up -d --build
```

HTTPS 正式部署需先放置证书：

```text
certs/fullchain.pem
certs/privkey.pem
```

然后使用 override：

```bash
docker compose -f docker-compose.prod.yml -f docker-compose.https.yml --env-file .env up -d --build
```

健康检查：

```bash
curl http://localhost/health
```

前端默认访问 nginx 入口：

```text
http://localhost
```

## 本地验证

后端：

```bash
cd backend
python3 -m compileall -q app tests
python3 -m pytest
```

前端：

```bash
cd frontend
npm run lint
npm run build
```

## 已知交付边界

- 用户 API Key 通过前端设置页录入，后端只保存 Fernet 加密密文。
- `apiports` 图片编辑走 `/chat/completions` 多模态参考图路径；`codeproxy` 图片编辑走 `/images/edits`。
- A/B/C 三套内容必须各选择一条文案，并且每套选满配置的图片数量后才能提交审核。