发布配置

本项目有两种独立的版本：上游框架组件包使用 lib-vX.Y.Z，本项目镜像使用 vX.Y.Z。packages/server/gradle.properties 中的 weiran.upstream.version 决定后端构建下载的组件版本；推送本项目的 vX.Y.Z 标签会发布镜像和中文 GitHub Release，不会发布上游组件包。

1. 配置 GitHub 仓库

在本项目 GitHub 仓库的 Settings → Secrets and variables → Actions → Repository secrets 配置：

Secret	用途	何时需要
ACR_USERNAME	登录 kjs-dw-mogu-registry.cn-hangzhou.cr.aliyuncs.com 并推送镜像	必填
ACR_PASSWORD	上述账号的密码或可用于登录的凭证	必填
WEIRAN_PACKAGES_USER	读取 weiran-tech/weiran4j GitHub Packages 的 GitHub 用户名	上游包未授权本仓 Actions 读取时配置
WEIRAN_PACKAGES_TOKEN	具备 read:packages 权限、且可读取上游包的 classic PAT	上游包未授权本仓 Actions 读取时配置

后端 CI 和镜像构建优先使用 WEIRAN_PACKAGES_USER、WEIRAN_PACKAGES_TOKEN；未配置时使用工作流的 github.actor、GITHUB_TOKEN（工作流已声明 packages: read）。若使用 GITHUB_TOKEN，还须在上游 GitHub Packages 的包设置中授予本仓 Actions 读取权限。classic PAT 所属账号也须有上游包的读取权限，详见 GitHub Gradle registry 认证说明。GitHub CLI 的设备授权仅作用于本机，不会自动传给 Actions。不要将 PAT 写入仓库、Gradle 文件、Docker 构建参数或部署 .env；镜像工作流通过 BuildKit secret 临时传入令牌。

本机执行 Gradle 时，在用户级 ~/.gradle/gradle.properties 设置 gpr.user、gpr.key，或临时提供 GITHUB_ACTOR、GITHUB_TOKEN。这组凭证只用于构建时下载依赖，运行中的服务器无需 GitHub Packages 令牌。

2. 确认构建和镜像目标

提交发布代码前，用 JDK 21 执行后端格式化和检查，并运行仓库门禁：

cd packages/server
export JAVA_HOME=$(/usr/libexec/java_home -v 21)
./gradlew spotlessApply
./gradlew check --no-daemon
cd ..
pnpm lint
pnpm test
pnpm build
pnpm openspec:check

推送 vX.Y.Z 格式的标签会触发 Docker images 工作流。普通分支推送不会触发镜像发布。工作流构建三个镜像，并向阿里云 ACR 同时推送版本号和 latest：

服务	镜像名	默认宿主机端口
后端	zhongxi-backend	仅 Compose 内网 5300
后台	zhongxi-web	5302
站点	zhongxi-site	5304

三个镜像的完整地址前缀为 kjs-dw-mogu-registry.cn-hangzhou.cr.aliyuncs.com/imvkmark/。例如标签 v0.3.0 会生成 zhongxi-backend:0.3.0 和 zhongxi-backend:latest。确认版本号尚未使用后，发布命令：

git tag v0.3.0
git push origin v0.3.0

标签应指向已推送且检查通过的提交。工作流先运行 .github/scripts/release-notes.sh 校验中文说明；若提交标题没有中文，须在创建标签前加入 .github/release-notes/vX.Y.Z.md 编写中文发布说明。三个镜像均推送成功后，工作流使用该说明创建 GitHub Release。推送后在 Actions 确认三个矩阵任务和 Release 任务均成功，再到 ACR 确认对应的版本号与 latest 标签。若后端依赖下载失败，先检查上游包的读取授权或 WEIRAN_PACKAGES_* Secrets；若镜像登录或推送失败，检查 ACR_* Secrets 和 ACR 仓库权限。

3. 配置部署服务器

部署文件在仓库的 deploy/。将该目录的 compose.yml、deploy.sh、.env.example 和 config/ 放在同一目录，在服务器上执行：

cp .env.example .env
openssl rand -base64 48  # 把结果填入 .env 的 WEIRAN_JWT_SECRET
docker login kjs-dw-mogu-registry.cn-hangzhou.cr.aliyuncs.com -u '<ACR 用户名>'
./deploy.sh

至少填写 .env 中的 WEIRAN_DB_URL、WEIRAN_DB_USERNAME、WEIRAN_DB_PASSWORD、WEIRAN_JWT_SECRET、WEIRAN_PUBLIC_BASE_URL，并按实际 HTTPS 入口设置 WEIRAN_COOKIE_SECURE。MySQL 使用已有线上库，Compose 不会启动 MySQL；部署前确认目标库并完成备份，数据库账号需能执行 Flyway 迁移。短信、OSS 等服务按需填写 WEIRAN_SMS_*、WEIRAN_STORAGE_*。config/application-prod.yml.example 可复制为 config/application-prod.yml，仅在需要额外 Spring 配置时使用。

deploy.sh 校验 Compose 配置、拉取三个 latest 镜像、更新容器，并等待后端 /api-backend/n/health 通过。compose.yml 默认对外开放后台 5302、站点 5304；生产环境在这些端口前配置 HTTPS 反向代理。前端 API 必须同源转发到后端。部署与健康检查的细节见仓库中的 deploy/README.md，认证、数据库和反向代理约束见 packages/server/docs/02-部署.md。

Compose 固定拉取 latest；它不按版本号固定镜像。需要回退时，先确认目标版本镜像在 ACR 中存在，再将 compose.yml 中三个镜像的标签改为该版本并重新部署，同时核对数据库迁移的兼容性。