91 lines
4.2 KiB
Markdown
91 lines
4.2 KiB
Markdown
# 部署与运维手册
|
||
|
||
## 环境变量
|
||
|
||
| 变量 | 必需 | 说明 |
|
||
|---|---|---|
|
||
| `NODE_ENV` | 是 | 正式环境设为 `production` |
|
||
| `PORT` | 否 | API 与生产静态站端口，默认 `3010` |
|
||
| `DATABASE_URL` | 正式环境 | PostgreSQL 连接串；缺省时使用 SQLite |
|
||
| `PGSSL` | 否 | 内网 PostgreSQL 可设为 `disable` |
|
||
| `PG_POOL_MAX` | 否 | 连接池上限，默认 `10` |
|
||
| `CORS_ORIGIN` | 公网分离部署 | 允许来源，多个值以逗号分隔 |
|
||
| `POSTGRES_PASSWORD` | Docker | `compose.yaml` 使用的数据库密码 |
|
||
| `COS_CONFIG_ENCRYPTION_KEY` | 正式环境 | 至少 32 字符的稳定随机密钥 |
|
||
| `INITIAL_ADMIN_USERNAME` | 首次初始化 | 平台管理员账号，默认 `admin` |
|
||
| `INITIAL_ADMIN_DISPLAY_NAME` | 首次初始化 | 平台管理员显示名 |
|
||
| `INITIAL_ADMIN_PASSWORD` | 首次初始化 | 空 PostgreSQL 必须提供的临时密码 |
|
||
|
||
真实环境变量只放在部署平台或未提交的 `.env` 中。
|
||
|
||
## 部署
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
# 编辑 .env 后：
|
||
docker compose up -d --build
|
||
```
|
||
|
||
在 HTTPS 反向代理后公开应用。不要直接提交 TLS 私钥、数据库文件、`.env`、`data/` 或 `uploads/`。
|
||
|
||
## 冒烟检查
|
||
|
||
```bash
|
||
curl http://127.0.0.1:3010/api/health
|
||
docker compose ps
|
||
docker compose logs --tail=100 app
|
||
```
|
||
|
||
健康接口应返回 `success: true`，且正式环境的 `database` 应为 `postgres`。
|
||
|
||
## COS 配置
|
||
|
||
1. 使用平台管理员进入“平台管理 → 腾讯云 COS”。
|
||
2. 填写地域、带 APPID 的存储桶名、公开访问域名、可选 CDN 域名、路径前缀及密钥。
|
||
3. 保存后执行连接测试。
|
||
4. 测试通过后启用配置。
|
||
|
||
连接测试会真实执行一次上传、读取和删除，因此密钥至少需要目标前缀的这三项权限。测试对象会尽力清理；请求中断时可检查 `<path-prefix>/.delivery-desk-check/` 是否残留临时文件。
|
||
|
||
COS 使用公开 URL。公共访问域名和 CDN 域名必须能够解析到公网地址，本机、私有网段、局域网或保留地址会在保存配置时被拒绝。必须关闭桶列表功能并使用不可枚举对象名；拿到 URL 的人可以直接访问文件。
|
||
|
||
JSON URL 导入依赖活动 COS 配置。同一 COS/CDN 域名的图片直接使用；其他域名会下载并按内容哈希写入 `<path-prefix>/imports/`。服务会拒绝内网地址、非图片响应和超过 20 MB 的文件，因此部署网络必须允许访问确需导入的公开图片源。
|
||
|
||
使用 `pnpm server:prod` 运行本地 API 时不会监听源码变化；后端代码更新后必须重启进程。日常开发应使用 `pnpm server:dev` 或 `pnpm dev`。
|
||
|
||
## Agent 上传 Skill 维护
|
||
|
||
Agent 通过 API 新建作品或提交验收轮次时，使用 `.agents/skills/upload-delivery-desk-work`。API Key 只通过 `DELIVERY_DESK_API_KEY` 环境变量注入，不写入计划文件、文档或 Git。
|
||
|
||
Agent 可用 `--image-url` 提交公网图片，也可用 `--image-file` 将生成在运营电脑上的本地图片直接 multipart 上传；两种模式不混用，不把图片转换为 Base64。
|
||
|
||
```powershell
|
||
python tests/test_upload_skill.py
|
||
powershell -ExecutionPolicy Bypass -File scripts/package-upload-skill.ps1
|
||
```
|
||
|
||
打包脚本会先运行回归测试，再生成 `skill-packages/upload-delivery-desk-work.zip`，并校验 ZIP 根目录直接包含 `SKILL.md`。计划文件写入已忽略的 `tmp/`；接口或层级变化后必须同步更新 Skill、测试和分发包。
|
||
|
||
## 数据备份与恢复
|
||
|
||
- PostgreSQL 使用托管备份或定期 `pg_dump`，恢复流程需在预发布环境演练。
|
||
- COS 开启版本控制或生命周期策略前先评估成本。
|
||
- 本地 SQLite 的 `data/` 只用于开发，不作为正式备份方案。
|
||
- `COS_CONFIG_ENCRYPTION_KEY` 必须与数据库备份一同安全托管；遗失后无法解密已保存的 COS 凭证。
|
||
|
||
## 发布前检查
|
||
|
||
```bash
|
||
pnpm install --frozen-lockfile
|
||
pnpm check
|
||
pnpm lint
|
||
pnpm build
|
||
pnpm test:review-rounds
|
||
pnpm test:collection-status
|
||
pnpm test:postgres-runtime
|
||
pnpm db:postgres:validate
|
||
python tests/test_upload_skill.py
|
||
```
|
||
|
||
正式切换前还应验证：管理员首次改密、客户访问门禁、COS 上传、客户批注与验收、数据库备份及 HTTPS Cookie。
|