部署与运维手册

环境变量

变量	必需	说明
`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 中。

部署

cp .env.example .env
# 编辑 .env 后：
docker compose up -d --build

在 HTTPS 反向代理后公开应用。不要直接提交 TLS 私钥、数据库文件、.env、data/ 或 uploads/。

冒烟检查

curl http://127.0.0.1:3010/api/health
docker compose ps
docker compose logs --tail=100 app

健康接口应返回 success: true，且正式环境的 database 应为 postgres。

COS 配置

使用平台管理员进入“平台管理 → 腾讯云 COS”。
填写地域、带 APPID 的存储桶名、公开访问域名、可选 CDN 域名、路径前缀及密钥。
保存后执行连接测试。
测试通过后启用配置。

连接测试会真实执行一次上传、读取和删除，因此密钥至少需要目标前缀的这三项权限。测试对象会尽力清理；请求中断时可检查 <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。

Skill 默认固定连接 http://192.168.30.90:3010，不读取环境变量覆盖服务地址。只有操作者明确要求迁移或测试其他环境时，才使用 --base-url 指定另一地址。

Agent 可用 --image-url 提交公网图片，也可用 --image-file 将生成在运营电脑上的本地图片直接 multipart 上传；两种模式不混用，不把图片转换为 Base64。

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 凭证。

发布前检查

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

4.4 KiB Raw Blame History Unescape Escape