Merge branch 'dev'

docs/guides/branch-environment-installation.md

@@ -1,10 +1,13 @@
 # CTMS 安装步骤向导
 
-按目标分支选择对应章节执行：
+推荐使用安装脚本完成 Docker 部署、环境变量、健康检查和数据迁移。手工步骤保留为排障附录。
 
-- [dev 分支安装](#dev-分支安装)
-- [main 分支安装](#main-分支安装)
-- [release 分支安装](#release-分支安装)
+- [安装前准备](#安装前准备)
+- [推荐脚本安装](#推荐脚本安装)
+- [手工安装/排障：dev 分支](#手工安装排障dev-分支)
+- [手工安装/排障：main 分支](#手工安装排障main-分支)
+- [手工安装/排障：release 分支](#手工安装排障release-分支)
+- [常见安装问题](#常见安装问题)
 
 ## 安装前准备
 
@@ -89,7 +92,61 @@ grep -n "^\\.env\\.\\*$" .gitignore
 
 预期能看到 `.env` 和 `.env.*` 已被忽略。
 
-## dev 分支安装
+## 推荐脚本安装
+
+安装脚本入口：
+
+```bash
+bash scripts/install-ctms.sh dev|main|release [选项]
+```
+
+常用示例：
+
+```bash
+bash scripts/install-ctms.sh dev
+bash scripts/install-ctms.sh main --base-url http://127.0.0.1:8888
+bash scripts/install-ctms.sh release --base-url https://ctms.example.com
+```
+
+可选参数：
+
+```text
+--base-url <url>   健康检查使用的访问地址。dev/main 默认 http://127.0.0.1:8888，release 必填或交互输入。
+--yes              跳过交互确认，适合自动化执行。
+--skip-build       跳过 docker compose up -d --build。
+--skip-migrate     跳过 alembic upgrade head。
+```
+
+脚本会执行：
+
+```text
+1. 检查 docker、docker compose、openssl、curl。
+2. 创建或更新 .env；已有 .env 会先备份为 .env.bak.<时间戳>。
+3. main/release 缺少 JWT 或 RSA 私钥时自动生成，已有有效密钥保持不变。
+4. main/release 先执行 backend-init。
+5. 执行 docker compose up -d --build。
+6. 执行 docker compose run --rm backend python -m alembic upgrade head。
+7. 检查容器状态、后端环境、/health、/api/v1/auth/login-key。
+```
+
+脚本不会执行：
+
+```text
+git checkout
+git pull
+docker compose down -v
+删除 pg_data
+删除数据库 volume
+自动安装系统依赖
+```
+
+如果只想查看参数说明：
+
+```bash
+bash scripts/install-ctms.sh --help
+```
+
+## 手工安装/排障：dev 分支
 
 ### 1. 切换分支
 
@@ -184,7 +241,7 @@ npm run build
 cd ..
 ```
 
-## main 分支安装
+## 手工安装/排障：main 分支
 
 ### 1. 切换分支
 
@@ -213,6 +270,12 @@ openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out login_rsa_main
 awk '{printf "%s\\n", $0}' login_rsa_main.pem
 ```
 
+也可以直接生成完整的 `.env` 配置行，复制输出结果替换 `.env` 中的 `LOGIN_RSA_PRIVATE_KEY`：
+
+```bash
+printf 'LOGIN_RSA_PRIVATE_KEY=%s\n' "$(awk '{printf "%s\\n", $0}' login_rsa_main.pem)"
+```
+
 ### 3. 写入环境配置
 
 在仓库根目录创建或覆盖 `.env`，将占位符替换为上一步生成的值：
@@ -339,7 +402,7 @@ npm run build
 cd ..
 ```
 
-## release 分支安装
+## 手工安装/排障：release 分支
 
 ### 1. 切换分支
 
@@ -384,6 +447,12 @@ openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out login_rsa_rele
 awk '{printf "%s\\n", $0}' login_rsa_release.pem
 ```
 
+也可以直接生成完整的 `.env` 配置行，复制输出结果替换 `.env` 中的 `LOGIN_RSA_PRIVATE_KEY`：
+
+```bash
+printf 'LOGIN_RSA_PRIVATE_KEY=%s\n' "$(awk '{printf "%s\\n", $0}' login_rsa_release.pem)"
+```
+
 将 `login_rsa_release.pem` 保存到服务器安全目录或密钥管理系统。
 
 ### 4. 写入环境配置