部署与发布

SteamHarness Server 可以本地开发，也可以作为自托管服务部署。生产环境应把数据库、运行数据、对象存储和文档静态文件放在明确的持久化目录中。

环境划分

环境	用途	建议
开发环境	本地调试 Server	Server 部署变量从 *.env.example 复制到本机 .env；项目业务值在项目配置面板填写。真实 .env 由 Git 忽略。
生产环境	提供管理端、项目与数据 API	使用受保护的 CI/CD Variables 或只存在于部署主机的 .env.production。

首次运行 Server：

pnpm bootstrap
pnpm dev

生产构建和启动：

pnpm install --frozen-lockfile
pnpm build:all
pnpm start

不要提交真实 .env、数据库连接串或服务密钥。*.env.example 只维护变量结构和占位值。

持久化配置

至少为以下内容准备备份和写入权限：

变量	说明
STEAMHARNESS_SERVER_DATA_DIR	Server 运行数据、缓存和本地对象存储目录。
STEAMHARNESS_DATABASE_URL	PostgreSQL 连接串。
STEAMHARNESS_SERVER_DATABASE_POOL_MAX	每个连接池的最大连接数，必须为正整数；未设置时使用驱动默认值。共用数据库的多个进程需合并计算连接预算。
STEAMHARNESS_SERVER_HOST	监听地址；反向代理部署可设置为 127.0.0.1，未设置时保持默认监听行为。
STEAMHARNESS_STORAGE_DRIVER	对象存储后端，只接受 local：制品与头像写入本机磁盘。
STEAMHARNESS_LOCAL_STORAGE_ROOT	local 驱动使用的绝对路径。
STEAMHARNESS_PUBLIC_BASE_URL	管理端公开地址。
STEAMHARNESS_API_PUBLIC_BASE_URL	API 的公开 HTTP(S) origin。
STEAMHARNESS_DOCS_PUBLIC_BASE_URL	文档站点地址。

Server 不安装依赖、不构建或加载上传的项目代码。源码快照、头像、KV 和知识库数据都应纳入备份策略。

管理员名称与共享账号

初始化管理员的默认显示名称只在首次创建账号时使用。之后通过个人资料或用户管理修改的名称保存在 PostgreSQL 中，普通登录、初始化管理员登录和会话续期都会保留该名称。个人资料改名会同时更新认证账号与用户资料，修改邮箱或密码也不会恢复旧名称。

多个 Server 实例连接同一个 STEAMHARNESS_DATABASE_URL 时共享账号资料。排查名称不一致时，先确认各实例的数据库和账号 ID 一致，并确认所有实例都已更新；旧实例的登录逻辑可能重新写入旧名称。

健康检查与反向代理

启动后检查：

curl -i "$STEAMHARNESS_PUBLIC_BASE_URL/health"

反向代理应转发 HTTPS、Host 和 WebSocket 相关 header，并只公开需要的端口。健康检查失败时保留现有数据，先查看服务日志和数据库连接状态，再执行回滚或恢复。

Alpha 与正式版

Alpha 和正式版使用独立的运行目录、进程、日志和端口。两套环境应使用明确的发布制品和迁移策略；数据库变更保持 expand-only，禁止在部署脚本中删除或重命名线上字段。

发布流水线只从受保护 ref 读取生产变量，并校验构建版本和静态资源。恢复操作不删除数据卷、不提交运行时配置，也不把密钥写入 artifact。

健康信息中的 deployment.server 与 deployment.serverWeb 可携带独立的 deploymentId。相同产品版本多次部署时，用该标识和 commitSha 区分实际来源；currentRelease.docsUrl 指向本次部署的同语言日志，旧发布元数据继续使用版本日志地址。