1

docs/technical/JENKINS_RUST_BUILD_DEPLOY_PIPELINES_2026-04-23.md

@@ -25,6 +25,7 @@
 9. 由于 Jenkins Pipeline 的 `build` 步骤触发下游时，原因类型通常是 `org.jenkinsci.plugins.workflow.support.steps.build.BuildUpstreamCause`，实现上需要同时兼容它和经典的 `hudson.model.Cause$UpstreamCause`，否则会把真实的上游触发误判成人工执行。
 10. 如果线上进程的启停必须经过 `sudo`，只允许 `start.sh` / `stop.sh` 这两个 hook 使用 `sudo -n` 执行，部署目录清空与文件覆盖仍保持普通权限。
 11. `WEB_PORT` 必须在 `构建并部署` 与 `部署` 两条流水线之间使用同名参数传递；部署脚本会把最终端口写入固定部署目录 `.env.local` 的 `GENARRATIVE_WEB_PORT`，避免 `sudo` 启动 hook 时环境变量被清理导致端口回退。
+12. `DATABASE` 必须使用 SpacetimeDB CLI 可接受的名称字符：数字、字母、点和短横线；不要使用下划线，否则 `spacetime publish` 会报 `invalid characters in database name`。
 
 ## 3. 节点与工作区要求
 
@@ -170,6 +171,7 @@ jenkins/Jenkinsfile.build-and-deploy
 4. `CLEAR_DATABASE`
 5. `MIGRATE_ON_CONFLICT`
 6. `MIGRATION_DIRECTORY`
+7. `DATABASE`：发布包默认数据库名，默认 `genarrative-pipeline-local-test`，只能包含数字、字母、点和短横线。
 
 如果你选择启用 `RUN_DEPLOY_HOOKS_WITH_SUDO=true`，推荐提前在服务器上增加一份最小 sudoers 配置，例如：