access-manage/docs/ENVIRONMENT_DEPLOYMENT.md

环境拆分与流水线规则

本项目拆分为测试环境和生产环境两套独立环境。两套环境使用不同部署目录、环境变量文件、数据库端口和数据目录，避免测试迭代影响生产。

环境约定

环境	触发方式	代码依据	默认部署目录	默认应用端口	默认数据库端口	数据目录
测试环境	develop 合并后自动触发 Jenkins	develop 最新提交	/srv/www/test/access-manage/current	3501	3308	/srv/data/test/access-manage/mysql
生产环境	Jenkins 手动触发	Gitea 项目 Tag	/srv/www/production/access-manage/current	3500	3307	/srv/data/production/access-manage/mysql

生产环境禁止因代码合并自动部署。生产部署时必须在 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 对应的提交，再部署。

服务器环境变量

测试和生产的真实环境变量必须留在服务器，不提交到仓库。

生成测试环境：

cd /srv/www/test/access-manage
bash deploy/server/create-env.sh /srv/www/test/access-manage test
docker-compose --env-file .env.test.mysql -f deploy/server/docker-compose.mysql.test.yml up -d mysql

生成生产环境：

cd /srv/www/production/access-manage
bash deploy/server/create-env.sh /srv/www/production/access-manage production
docker-compose --env-file .env.production.mysql -f deploy/server/docker-compose.mysql.production.yml up -d mysql

部署脚本默认会读取：

/srv/www/test/access-manage/shared/.env.test
/srv/www/production/access-manage/shared/.env.production

如果使用 create-env.sh 在 current 外生成了 env 文件，请把对应文件放到 shared/ 下，或者在服务器上建立等价软链。

生产发布流程

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 "access-manage production release 2026-06-05"
git push origin v2026.06.05-1

部署脚本

deploy/jenkins/deploy-backend.sh 会把 dist/、migrations/、deploy/、package.json 和 pnpm-lock.yaml 发布到：

${DEPLOY_BASE_DIR}/${DEPLOY_ENV}/access-manage/releases/<build>-<commit>

并更新：

${DEPLOY_BASE_DIR}/${DEPLOY_ENV}/access-manage/current

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

DEPLOY_REMOTE=user@server

如果需要部署后自动安装依赖、执行迁移和重启服务，在 Jenkins 中配置：

DEPLOY_POST_DEPLOY_CMD=pnpm install --prod --frozen-lockfile && pnpm db:migrate:prod && systemctl restart access-manage-production

测试环境应配置独立命令，例如使用 .env.test 和独立服务名。