zijunchiang/opendance-web
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 17 Wiki Activity
Files
06c2fd688b57b2493d3f28191115ca68498072b6
opendance-web/tasks/010-deploy.md
T

17 KiB
Raw Blame History

T-WEB-010 部署（Linux 业务服务，不使用 Docker，不部署反代）

  • 状态：done（两次需求变更后重做）
  • 依赖：T-WEB-001 ~ 009

目标

Web 服务端以一个 Linux 业务服务的形式部署运行：Node 进程由系统服务 （systemd / OpenRC / SysVinit / 后台进程）托管，同时提供 REST API 与管理端页面。 不使用 Docker，不部署 MySQL（数据库为部署方提供的现有实例）， 也不部署反向代理（由另外的服务/团队负责）。

需求变更记录

  1. 初版按文档 4.4 实现为 Docker Compose；用户要求改为"运行在 Linux 的网站"， 于是替换为 nginx + systemd 原生站点部署，并删除 deploy/docker-compose.yml、 web-server/Dockerfile、web-server/admin/Dockerfile。
  2. 随后用户明确："web 端仅需要业务需求，反代等工作交由另外的服务处理。 只需要给出 iis 和 nginx 反代的说明文档，不用部署反代服务。" 于是 install.sh 彻底移除 nginx 的安装与站点配置，管理端改由 Node 服务自身 托管（ADMIN_DIR + SPA 深链接回退），并新增 deploy/proxy/ 只交付说明文档。
  3. 再随后用户要求管理端口与软件 API 端口分离：新增 ADMIN_PORT （默认 PORT + 1）与可选的 ADMIN_HOST（默认跟随 HOST）。软件 API 端口 只给客户端调接口（/api、/health、/static、/contracts，/ 等返回 404）， 管理端端口给浏览器（管理页面 + 全部接口）。ADMIN_PORT === PORT 保留为 单端口兼容模式，只 warn 不中止。install.sh 的汇总与反代说明改为两个端口。
  4. 本次追加两项： a) 首次启动的.env 引导：新增 deploy/init-env.sh（交互式逐项询问数据库 与端口，写盘前校验必填项/端口范围，可用 Node + mysql2 做连通性自检）； install.sh 在缺 deploy/.env 时先调用它，失败才 die（安装目录已有上次 安装留下的.env 则直接复用，保持原语义）。 b) 默认监听 0.0.0.0 固化：确认 configuration.ts 的 bindHost = process.env.HOST?? '0.0.0.0'、adminHost 默认跟随 HOST， 两个 .env.example 与 init-env.sh 的 HOST 默认值均为 0.0.0.0。

load

DSH.md
contracts/database.md
deploy/init-env.sh
deploy/install.sh
deploy/uninstall.sh
deploy/.env.example
deploy/systemd/opendance-api.service
deploy/proxy/README.md

部署形态

职责边界：本端只提供业务服务；反向代理由另外的服务/团队负责。

Windows/Godot 客户端、Android App ─▶ 软件 API 端口:3000（只提供接口，无管理页面）
                                        ├── /api/        REST API
                                        ├── /health      健康检查（数据库不可用返回 503）
                                        ├── /static/     上传文件
                                        └── /contracts/  契约快照
                                        （/、/songs 等返回 404，有意设计）

浏览器 ─▶ 反向代理（外部提供，IIS / nginx / 网关...）──▶ 管理端端口:3001
              │  整端口转发，不需要托管静态文件      ├── /            管理端页面（含 SPA 深链接回退）
              │                                      ├── /assets/     前端静态资源
              │                                      └── 上面全部接口
              ▼
        现有 MySQL / MariaDB 实例（两个端口共用同一 Node 进程）

本服务一个 Node 进程同时监听两个端口（软件 API 端口 + 管理端端口）， 管理页面只在管理端口提供；反代按用途分别转发，每个端口各一条全匹配规则即可， 既不用在代理层托管静态文件，也不用配置 SPA 回退（try_files）。

deploy/install.sh 不安装、不配置任何反向代理软件，收尾时只打印反代交接指引。

交付物

文件 说明
deploy/install.sh 一键部署：前置检查 -> 建用户/目录 -> 复制并校验文件 -> 装依赖 -> 迁移 -> 注册系统服务 -> 健康检查；汇总打印两个端口与防火墙放行提示；缺 deploy/.env 时先调用 init-env.sh 引导
deploy/init-env.sh 首次启动的 .env 交互引导：逐项询问 8 个键、写盘前校验必填项与端口范围、可选数据库连通性自检；只替换/追加这 8 个键并保留模板注释，写完 chmod 600 并回读；--check / -y 等非交互模式下绝不阻塞
deploy/uninstall.sh 卸载；默认保留上传数据，--purge 才删除
deploy/.env.example 部署环境变量样例（PORT / ADMIN_PORT / ADMIN_HOST / HOST 说明与上传上限告警）
deploy/systemd/opendance-api.service systemd 单元，含 ProtectSystem=strict 等安全加固
deploy/openrc/opendance-api OpenRC 服务脚本
deploy/initd/opendance-api SysVinit / LSB 启动脚本（转调 ctl.sh）
deploy/ctl.sh 无 init 系统时的进程控制（后台进程 + PID 文件），start/stop/restart/status/logs
deploy/proxy/README.md 反代说明文档：转发目标、绑定地址、自检清单、故障对照
deploy/proxy/nginx.conf.example nginx 配置样例（上传上限、超时、keepalive、可选 HTTPS）
deploy/proxy/web.config.example IIS 配置样例（需 ARR + URL Rewrite 模块）

deploy/.env 初始化引导（init-env.sh）

首次部署不再要求手工 cp deploy/.env.example deploy/.env && vi deploy/.env：

install.sh 检测到缺 deploy/.env
   ├── $APP_DIR/deploy/.env 存在 -> 直接复用（上次安装留下的配置，原语义保留）
   └── 否则调用 deploy/init-env.sh
         ├── 缺.env -> 从.env.example 复制，chmod 600
         ├── 交互（TTY / 管道）-> 逐项询问并写回
         └── 非交互（CI、</dev/null、-y）-> 只校验，绝不阻塞；失败则 install.sh die

逐项询问 DB_HOST / DB_PORT / DB_USER / DB_PASS / DB_NAME / PORT / ADMIN_PORT / HOST 共 8 个键，回车保留默认；DB_PASS 用 read -rs 不回显、按约定写盘不加引号； 校验必填项与端口范围；可用 Node + mysql2 做连通性自检（口令只经环境变量传给子进程， 失败仅告警）；只替换/追加这 8 个键、保留模板注释，写完 chmod 600 并回读校验； 结尾打印摘要（口令 ***）与本次变更列表。

开关 说明
（无） 交互引导；.env 已存在且必填项齐全时跳过询问
--force 已有 .env 也重新逐项询问
--check 只校验，不修改文件、不提问
-y / --yes / --non-interactive 非交互：只校验缺字段与端口，绝不提问
-i / --interactive 即使 stdin 不是 TTY 也强制提问（读取超时仍生效）
--skip-db-check 跳过数据库连通性自检
--dir DIR 等价于 --env-file DIR/.env --example DIR/.env.example
--env-file PATH / --example PATH 指定 .env / 模板路径
--timeout SECONDS 非 TTY 下每次读取超时秒数（默认 10）
-h / --help 显示帮助

环境变量：OPENDANCE_NONINTERACTIVE / OPENDANCE_INTERACTIVE / OPENDANCE_SKIP_DB_CHECK / OPENDANCE_ENV_FILE / OPENDANCE_ENV_EXAMPLE / OPENDANCE_PROMPT_TIMEOUT。

非交互绝不挂住：stdin 非 TTY 且是 </dev/null 或已关闭，或带 -y 等开关 -> 只校验不提问；所有 read 带超时，EOF/超时立即 exit 1。

默认监听 0.0.0.0：configuration.ts 的 bindHost = process.env.HOST?? '0.0.0.0'，adminHost 默认跟随 HOST （HOST 未设置时同样回落 0.0.0.0）；deploy/.env.example 与 web-server/.env.example 均写 HOST=0.0.0.0；install.sh 的 BIND_HOST="${HOST:-0.0.0.0}"；init-env.sh 的 HOST 默认值也是 0.0.0.0。 注意 install.sh 里的 HEALTH_HOST / API_HOST 用的是回环地址做本机健康检查， 与对外监听的默认值无关。

进程管理：四层降级

"运行在 Linux 上"不应等于"必须有 systemd"。安装时按以下顺序探测并选择：

1. systemd    /run/systemd/system 存在且 systemctl 可用
2. OpenRC     rc-service + rc-update 可用
3. SysVinit   /etc/init.d 存在且 update-rc.d 或 chkconfig 可用
4. 都没有     nohup 后台进程 + PID 文件（deploy/ctl.sh）
              并写 crontab @reboot 实现开机自启

三种 init 方式最终都调用同一个 Node 进程，只是守护方式不同；第 4 种由 deploy/ctl.sh 提供 start/stop/restart/status/logs。 （注意：nohup 不能调用 shell 函数，故 ctl.sh 用 spawn_service_process() 拼装外部命令，而非包装函数。）

不使用 sudo：脚本已要求 root，降权到服务用户用 runuser -> setpriv -> su 依次回退（部分服务器根本没装 sudo）。

关键实现

  • 双端口：一个 Node 进程创建两个 HTTP server--软件 API 端口（PORT，默认 3000） 与管理端端口（ADMIN_PORT，默认 3001），复用同一个 express 实例；用 req.socket.localPort 判断请求来自哪个端口，决定是否提供管理页面。 ADMIN_PORT === PORT 时只建一个 server（单端口兼容模式，避免 EADDRINUSE）
  • 服务自身托管管理端：app.useStaticAssets(adminDir,...) + SPA 回退中间件 （仅管理端口生效）；回退会跳过 /api/、/health、/static/、/contracts/ 以及带扩展名的路径，保证未知 API 仍返回 404 而不是 HTML
  • 软件 API 端口不提供管理页面：/、/songs 等在该端口一律 404（有意设计）
  • HOST / ADMIN_HOST 绑定地址：同机反代建议 127.0.0.1，异机反代用 0.0.0.0 + 防火墙；ADMIN_HOST 可选（默认跟随 HOST），可单独把管理端限制在 本机或内网；HOST 默认取 0.0.0.0 以保证开箱可用
  • 首次部署的.env 由引导生成：install.sh 缺 deploy/.env 时先调用 deploy/init-env.sh（安装目录已有上次安装的 .env 则直接复用）；引导脚本在 非交互环境下只校验、绝不阻塞，校验失败时 install.sh 才 die
  • 端口校验：PORT / ADMIN_PORT 必须是 1..65535 的整数；非法值在生产环境 启动时快速失败（validateEnv 的 errors），ADMIN_PORT === PORT 只 warn
  • install.sh 汇总与反代说明：结尾分别打印两个端口的访问地址、监听配置与 防火墙放行命令（firewall-cmd / ufw 同时放行两个端口）
  • systemd 加固：NoNewPrivileges、ProtectSystem=strict、ProtectHome、 ReadWritePaths=/var/lib/opendance，进程只能写自己的存储目录
  • 上传上限两侧一致：后端 UPLOAD_MAX_BYTES=536870912（512 MiB）， 反代侧 client_max_body_size / maxAllowedContentLength 必须不小于此值
  • 模型转换配置（deploy/.env.example 已写入）：
    • ASSIMP_BIN=assimp：上传 .zip 模型包或 .pmx/.fbx 单文件时必须能调用到， 否则转换失败 422
    • MODEL_CONVERT_FORMAT=glb（默认）|vrm：只影响需要转换的 PMX/FBX 的交付格式。 glb 通用，两个客户端都原生加载；vrm 在 GLB 之上补 VRMC_vrm 扩展 （humanoid 骨骼 / 表情语义），humanoid 骨骼名映射不全时自动回退交付 GLB 并写进 models.conversion_note。产物一律 assimp info 回读校验
    • MODEL_CONVERT_PMX / MODEL_CONVERT_TIMEOUT_MS 语义见 README 四
  • 迁移用编译产物：web-server/scripts/migrate.mjs 检测到 dist/ 时走 typeorm -d dist/db/data-source.js，无需在服务器上装 devDependencies； 本版本迁移共 3 个：InitSchema1789382903060、 AddModelConversionFields1789450000000、AddModelStats1789460000000 （新增 models.stats TEXT，存模型分析结果，已在真实库执行）
  • 依赖安装显式带 dev：安装脚本先 set -a;. deploy/.env 导出了 NODE_ENV=production，会让 npm 跳过 devDependencies 导致 tsc: not found； 故用 env -u NODE_ENV npm ci --include=dev
  • 复制文件时锚定排除：storage/ 这类模式会误伤 src/storage/ 与 dist/storage/ （曾导致 MODULE_NOT_FOUND...storage.module），排除规则一律用 /storage/ 锚定
  • /contracts/ 静态暴露：另两端可直接从站点取契约快照

验收

bash deploy/init-env.sh              # 或手工 cp deploy/.env.example deploy/.env 后填写 DB_*
bash deploy/install.sh               # 需 root（不需要 sudo）
curl -fsS http://localhost:3000/health
curl -fsS http://localhost:3001/health
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3000/   # 期望 404（软件 API 端口无管理页面）
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3001/   # 期望 200（管理页面）
验收项 状态
deploy/install.sh 脚本语法与幂等性 ✅ bash -n 通过；重复执行会覆盖程序文件、保留 .env
连接现有 MySQL 成功 ✅ 已用真实实例验证（/health 200，database.connected=true）
TypeORM migration 执行成功 ✅ 5 张业务表已创建并验证；v0.2.0 的 AddModelStats1789460000000（models.stats TEXT）已在真实库执行
模型转换配置 ✅ deploy/.env.example 写入 ASSIMP_BIN / `MODEL_CONVERT_FORMAT=glb
curl http://<host>:3000/health 通过 ✅ 直连后端端口已验证
软件 API 端口 / 返回 404 ✅ PORT=3000 上 /、/songs 均 404（有意设计，无管理页面）
管理端端口 / 返回 200 ✅ ADMIN_PORT=3001 上 /、/songs、/models 均返回同一份 HTML（200）
前端深链接回退 ✅ 未知静态路径回退到 index.html，未知 API 仍 404
ADMIN_PORT === PORT 单端口兼容模式 ✅ 只建一个 server，管理页面回到 API 端口，日志提示「未分端口」
端口非法在生产环境中止启动 ✅ validateEnv 对非 1..65535 整数端口报 error
不部署、不管理 MySQL ✅ 部署脚本不含任何数据库安装/建库操作
不使用 Docker ✅ 仓库内已无 Dockerfile / docker-compose / Docker 引用
不部署反向代理 ✅ 仅交付 deploy/proxy/ 文档，install.sh 中无任何反代安装动作
缺 deploy/.env 时由 init-env.sh 引导 ✅ 交互逐项询问 8 个键；只改这 8 个键、保留模板注释、chmod 600、回读校验；安装目录已有 .env 时直接复用
init-env.sh --check / 非交互不阻塞 ✅ test/init-env.spec.ts（16 项）覆盖 --check、-y、EOF/超时立即退出、口令不加引号写盘
HOST 默认 0.0.0.0 ✅ configuration.ts、deploy/.env.example、web-server/.env.example、install.sh、init-env.sh 五处一致

环境限制说明：本次执行环境无 root 权限，且未安装 nginx（按需求也不应安装）。 因此 deploy/install.sh 的服务注册链路（systemd / OpenRC / SysVinit / crontab） 未能在本机实机跑通。已完成的等价验证：

  • 后端以 node dist/main.js 直连真实数据库启动，两个端口 /health 均 200
  • 管理端托管与 SPA 回退逐路径实测（/、/songs、/models、/api/*、未知路径）， 并确认 3000 上返回 404、3001 上返回 200
  • ADMIN_DIR 环境变量生效，index.html 缺失时打印告警而非崩溃
  • npm run migration:run 走编译产物成功
  • 端到端冒烟 57 项全通过
  • install.sh / uninstall.sh / ctl.sh 通过 bash -n 语法校验
  • init-env.sh 通过 bash -n，并由 test/init-env.spec.ts（16 项）覆盖 交互写回 / --check / 非交互 / 超时 / 幂等 / 口令不加引号
  • 反代文档中的占位符与后端实际行为逐条对照（两个端口、路径、上传上限、健康检查）

需在一台有 root 的 Linux 服务器上补做一次 install.sh 实机验收。

发布产物

./scripts/package-release.sh
# -> dist-release/opendance-web-v0.2.0.tar.gz

内容：web-server/（源码 + dist）、admin/（构建产物）、deploy/ （含 proxy/ 反代文档）、contracts/ 快照、THIRD_PARTY.md、README.txt。 打包脚本会对产物做硬校验：src/**/*.ts 必须都有对应 dist/*.js， 关键文件（dist/main.js、dist/storage/storage.module.js、admin/index.html、 deploy/proxy/*）必须齐全，且不得含真实 .env 与 Docker/nginx 安装配置。 v0.2.0 起校验清单追加模型新模块：dist/models/model-inspector.js、 dist/models/model-thumbnail.js、dist/models/vrm-writer.js、 dist/models/gltf-packer.js、dist/migrations/1789460000000-AddModelStats.js。

发布包名变更：opendance-web-v0.1.0.tar.gz -> opendance-web-v0.2.0.tar.gz （scripts/package-release.sh 的 VERSION 默认值已改为 0.2.0， 与 project.yaml 的 version: 0.2.0、web-server/package.json 一致）。

Reference in New Issue View Git Blame Copy Permalink