MemRelay/projects/d44c219a-0b31-4de1-b160-323eb34a4c6a/部署形态与配置契约.md

title, type, permalink, stable_id, scope, project_id, memory_type, status, revision, restored_from_commit, created_at, updated_at, tags

title	type	permalink	stable_id	scope	project_id	memory_type	status	revision	restored_from_commit	created_at	updated_at	tags
部署形态与配置契约	fact	main/projects/d44c219a-0b31-4de1-b160-323eb34a4c6a/部署形态与配置契约	b7e0eb44-e38f-40a3-8736-3a7a9de84818	project	d44c219a-0b31-4de1-b160-323eb34a4c6a	fact	active	1	6a6a895eaf	2026-09-23T15:08:14.210928+00:00	2026-09-23T15:08:14.210988+00:00	deployment config install docker baota

配置契约：唯一配置文件 = 运行目录下单一 .env（带中文注释，示例 .env.example），无 JSON 配置/config 目录；业务可调项（平台名/客户端地址/存储/链/备份/轮播间隔等）在系统设置表，优先于 .env。关键 env：DATABASE_URL、REDIS_*、JWT_SECRET、SETTING_ENCRYPTION_KEY、STORAGE_DRIVER=local|oss、BLOCKCHAIN_DRIVER=mock|tianhe、BASE_URL、API_PORT。 安装向导：无 .env 时 API 进 InstallAppModule 安装模式（只托管 admin 静态），访问 /admin 自动进向导：填对外地址/端口/MySQL/Redis/管理员 → 自动建库+migrate deploy+建超管 → 最后一步写 .env → 退出由 PM2/Docker 重启进正式模式。

三种部署形态共享上述契约：

1. 本地 scripts/dev.py。
2. 宝塔/PM2 非 Docker 发布包 python scripts/build.py（全新 artveris-fresh-*，含 init.sh/init.ps1、server.cjs、ecosystem.config.cjs、README-deploy.md）/ --upgrade（artveris-upgrade-*，含 upgrade.sh/upgrade.ps1，只替代码），产物在 .release/。init 会配国内 npm/Prisma 镜像、corepack 准备 pnpm 10、装生产依赖、prisma generate。宝塔 PM2 项目：启动文件 server.cjs，运行目录=发布根，实例 1。
3. 离线 Docker 包 build_docker.py（API/MySQL 8/Redis 7/Nginx 四镜像 + compose，Nginx 单入口 127.0.0.1:18080，数据 bind-mount data/{storage,backups,mysql,redis,tmp}，up.sh [upgrade|fresh|clean]）+ remote.py SSH 部署；密钥记忆在 .deploy/deploy-secrets.json（gitignore）。Docker 基础镜像 node:24-slim。

反向代理必须：client_max_body_size 0; proxy_read_timeout 3600s; proxy_send_timeout 3600s; proxy_request_buffering off;（大 ZIP 出库导入）。 安全：四角色 RBAC（SUPER_ADMIN 全通/OPERATOR 写/AUDITOR 审核/VIEWER 只读），JWT 每请求回库校验；限流登录 10/min、公开溯源 60/min/IP；安全头 nosniff 等；无效短码 Redis 负缓存；操作日志拦截全部写操作且递归脱敏密钥。 预览：后台点追溯码进 /trace/preview/:code，类 TOTP 令牌 HMAC(jwt.secret, 窗口号) 10 分钟周期接受当前+上一窗口，接口零副作用。