role-user/docs/ENVIRONMENT_DEPLOYMENT.md

环境拆分与流水线规则

role-user 是 Next.js standalone 服务。测试环境和生产环境通过独立部署目录、独立运行时环境变量和独立后端 API 地址拆分。

环境约定

环境	触发方式	代码依据	构建命令	默认部署目录	默认端口	后端 API
测试环境	develop 合并后自动触发 Jenkins	develop 最新提交	pnpm build:test	/srv/www/test/role-user/current	3211	http://127.0.0.1:3501/api
生产环境	Jenkins 手动触发	Gitea 项目 Tag	pnpm build:prod	/srv/www/production/role-user/current	3210	http://127.0.0.1:3500/api

生产环境禁止因代码合并自动部署。生产部署时必须在 Jenkins 参数中选择 DEPLOY_ENV=production 并填写已存在的 RELEASE_TAG。

Jenkins 参数

参数	说明
DEPLOY_ENV	test 或 production。默认 test。
RELEASE_TAG	生产环境必填，必须是 Gitea 仓库中已存在的 Tag。
SKIP_DEPLOY	为 true 时只执行安装、检查、构建，不部署。

Jenkinsfile 会强制校验：

• 测试环境只在 develop 分支自动部署。
• 生产环境必须手动触发。
• 生产环境必须填写 RELEASE_TAG。
• 生产环境构建会先 checkout 到该 Tag 对应的提交，再部署。

运行时环境变量

真实环境变量必须留在服务器，不提交到仓库。

部署脚本默认读取：

/srv/www/test/role-user/shared/.env.test
/srv/www/production/role-user/shared/.env.production

示例文件：

.env.test.example
.env.production.example

ACCESS_MANAGE_API_BASE_URL 是服务端 BFF 使用的运行时变量，不加 NEXT_PUBLIC_，不会暴露到浏览器 bundle。Cookie 名测试和生产应分开，避免同域下会话互相覆盖。

standalone 产物

next.config.ts 已启用 output: "standalone"。Jenkins 构建后会打包：

.next/standalone
.next/static
public

部署脚本会发布到：

${DEPLOY_BASE_DIR}/${DEPLOY_ENV}/role-user/releases/<build>-<commit>

并更新：

${DEPLOY_BASE_DIR}/${DEPLOY_ENV}/role-user/current

如果 Jenkins 不在目标服务器上运行，可以配置：

DEPLOY_REMOTE=user@server

生产发布流程

1. 在需要发布的提交上创建 Tag。
2. 推送 Tag 到 Gitea。
3. Jenkins 手动 Build With Parameters。
4. 选择 DEPLOY_ENV=production。
5. 填写 RELEASE_TAG。
6. 执行构建部署。

示例：

git tag -a v2026.06.05-1 -m "role-user production release 2026-06-05"
git push origin v2026.06.05-1