zhouchengcheng/ctms

Fork 0

Files

T

Cheng Zhou 4bbc234b53 同步工作区更新：优化安装脚本与更新脚本，添加文档与测试脚本

2026-06-23 17:18:34 +08:00

13 KiB

Raw Permalink Blame History

Git 仓库同步与在线更新指南

本文档包含两部分：

在线更新功能：使用 scripts/update.sh 从远程仓库拉取代码并自动部署
双仓库推送配置：配置 CTMS 项目的 GitHub 和 Gitea 双仓库同步

第一部分：在线更新功能

功能特性

🔐 安全保障

项目身份验证：自动检测项目特征文件，防止拉取错误仓库
自动备份：拉取前创建 Git tag 备份点，支持一键回滚
工作目录保护：检测未提交更改，提供暂存或放弃选项
多种认证方式：支持 SSH 密钥、Personal Access Token、用户名密码

✨ 易用性

交互式操作：友好的提示和参数预览
自动化支持：--yes 模式适配 CI/CD 流程
灵活配置：支持命令行参数和环境变量

快速开始

基础用法

# 交互式更新开发环境（会提示输入仓库地址和凭证）
bash scripts/update.sh dev

# 更新测试环境并指定仓库
bash scripts/update.sh main --repo-url https://github.com/user/ctms-dev.git

# 更新生产环境（指定分支）
bash scripts/update.sh release --repo-url https://gitea.example.com/team/ctms.git --branch main

认证方式

1. SSH 密钥（推荐，无需输入密码）

# 前提：已配置 SSH 公钥到 GitHub/Gitea
bash scripts/update.sh dev --repo-url git@github.com:user/ctms-dev.git

2. Personal Access Token（推荐用于 HTTPS）

# GitHub 生成 Token：Settings → Developer settings → Personal access tokens
# Gitea 生成 Token：Settings → Applications → Generate New Token

# 交互式输入（用户名输入 git 用户名，密码输入 Token）
bash scripts/update.sh main --repo-url https://github.com/user/ctms-dev.git

# 或通过环境变量（适合自动化）
export GIT_USERNAME="your-username"
export GIT_PASSWORD="ghp_xxxxxxxxxxxxxxxxxxxx"  # GitHub Token
bash scripts/update.sh main --repo-url https://github.com/user/ctms-dev.git --yes

3. 用户名密码（不推荐，安全性低）

# 交互式输入
bash scripts/update.sh dev --repo-url https://gitea.example.com/user/ctms.git
# 按提示输入用户名和密码

命令选项

环境参数（必需）

dev - 本地开发环境
main - 内网测试/预发布环境
release - 生产环境

可选参数

参数	说明	示例
`--repo-url <url>`	Git 仓库地址（HTTPS 或 SSH）	`--repo-url https://github.com/user/repo.git`
`--branch <name>`	指定拉取的分支（默认当前分支）	`--branch main`
`--yes`	跳过所有交互确认	`--yes`
`--force`	强制覆盖本地更改（`git reset --hard`）	`--force`
`--skip-backup`	跳过自动备份 tag（不推荐）	`--skip-backup`
`--skip-build`	透传给 install.sh：跳过镜像构建	`--skip-build`
`--skip-migrate`	透传给 install.sh：跳过数据库迁移	`--skip-migrate`
`--verbose`	透传给 install.sh：显示详细输出	`--verbose`

使用场景

场景 1：开发环境日常更新

# 拉取最新代码并重新部署
bash scripts/update.sh dev --repo-url https://github.com/team/ctms-dev.git

流程：

检查工作目录状态（如有未提交更改，提示处理方式）
创建备份 tag（如 pre-update-20260623-143022）
拉取远程代码
验证项目身份
自动调用 install.sh 重新构建容器和迁移数据库

场景 2：生产环境版本升级

# 使用 Personal Access Token 自动化更新
export GIT_USERNAME="deploy-bot"
export GIT_PASSWORD="ghp_xxxxxxxxxxxxxxxxxxxx"

bash scripts/update.sh release \
  --repo-url https://github.com/company/ctms.git \
  --branch v1.2.0 \
  --yes \
  --base-url https://ctms.example.com

注意：生产环境更新建议：

提前在测试环境验证
使用 --branch 指定稳定版本标签
备份数据库（脚本会自动创建 Git tag）
准备回滚方案

场景 3：强制覆盖本地更改

# 场景：本地有修改但需要强制同步远程版本
bash scripts/update.sh main --repo-url https://gitea.internal/team/ctms.git --force

警告：--force 会执行 git reset --hard，所有本地未提交更改将丢失。

场景 4：CI/CD 自动部署

# GitHub Actions 示例
name: Deploy to Main
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: self-hosted
    steps:
      - name: Update CTMS
        env:
          GIT_USERNAME: ${{ secrets.DEPLOY_USERNAME }}
          GIT_PASSWORD: ${{ secrets.DEPLOY_TOKEN }}
        run: |
          cd /opt/ctms
          bash scripts/update.sh main \
            --repo-url https://github.com/${{ github.repository }}.git \
            --branch main \
            --yes \
            --skip-backup

故障排查

问题 1：认证失败

症状：

✖ 出错 拉取失败，请检查网络连接和仓库权限

解决方案：

确认仓库地址正确
检查凭证是否有效（Token 是否过期）
确认账号有仓库访问权限
对于私有仓库，确保 Token 有 repo 权限

问题 2：项目身份验证失败

症状：

✖ 出错 项目身份验证失败：未检测到足够的 CTMS 项目特征文件

原因：拉取的仓库不是 CTMS 项目

解决方案：

检查 --repo-url 是否正确
确认远程仓库确实是 CTMS 项目
检查 --branch 参数是否指向正确分支

问题 3：合并冲突

症状：

✖ 出错 合并失败，可能存在冲突

解决方案：

方法 1：手动解决冲突

# 查看冲突文件
git status

# 手动编辑解决冲突
vim <conflict-file>

# 完成合并
git add .
git commit -m "Resolve merge conflict"

# 重新运行更新
bash scripts/update.sh dev

方法 2：强制覆盖

bash scripts/update.sh dev --force

问题 4：回滚到更新前版本

# 查看备份 tag
git tag | grep pre-update

# 回滚（示例）
git reset --hard pre-update-20260623-143022

# 重新部署
bash scripts/install.sh dev --skip-migrate

安全最佳实践

1. Personal Access Token 管理

GitHub：

生成路径：Settings → Developer settings → Personal access tokens → Tokens (classic)
最小权限：repo（私有仓库）或 public_repo（公开仓库）
设置过期时间，定期轮换

Gitea：

生成路径：User Settings → Applications → Manage Access Tokens
权限选择：read:repository

2. 环境变量保护

# 不要在脚本中硬编码密码
# ❌ 错误
export GIT_PASSWORD="my-secret-token"

# ✅ 正确：从加密的配置管理系统读取
export GIT_PASSWORD="$(vault kv get -field=token secret/git/deploy)"

3. 生产环境更新检查清单

已在测试环境验证更新
已备份数据库（除了 Git tag 备份）
已通知相关人员计划维护窗口
准备回滚脚本
确认 --base-url 参数正确
使用 --branch 指定稳定版本

常见问题

Q: 更新会丢失 .env 配置吗？
A: 不会。.env 在 .gitignore 中，不会被 Git 覆盖。

Q: 更新会清空数据库吗？
A: 不会。数据库数据持久化在 pg_data 目录，不受更新影响。更新只会执行增量迁移（alembic upgrade head）。

Q: 如何跳过数据库迁移？
A: 使用 --skip-migrate 参数：

bash scripts/update.sh dev --skip-migrate

Q: 支持 GitLab 吗？
A: 支持。GitLab 使用 HTTPS/SSH 认证方式与 GitHub/Gitea 相同。

Q: 能否在更新前先查看远程有哪些更新？
A: 可以手动执行：

git fetch origin
git log HEAD..origin/main  # 查看即将合并的提交

第二部分：双仓库推送配置

本部分说明如何配置 CTMS 项目的 GitHub 和 Gitea 双仓库推送与拉取。

仓库信息

GitHub 仓库: https://github.com/chengchengzhou7/CTMS.git
Gitea 仓库: http://119.29.208.238:8080/zhouchengcheng/ctms.git
项目分支: main (主分支)、dev (开发分支)、release (发布分支)

一、配置双推（同时推送到两个仓库）

1.1 查看当前配置

git remote -v

1.2 配置双推 URL

# 设置 fetch 源为 GitHub（用于拉取）
git remote set-url origin https://github.com/chengchengzhou7/CTMS.git

# 添加 GitHub 的 push URL
git remote set-url --add --push origin https://github.com/chengchengzhou7/CTMS.git

# 添加 Gitea 的 push URL
git remote set-url --add --push origin http://119.29.208.238:8080/zhouchengcheng/ctms.git

1.3 验证配置

git remote -v

预期输出：

origin  https://github.com/chengchengzhou7/CTMS.git (fetch)
origin  https://github.com/chengchengzhou7/CTMS.git (push)
origin  http://119.29.208.238:8080/zhouchengcheng/ctms.git (push)

二、账号密码管理

2.1 保存凭据（推荐）

使用 Git 凭据管理器保存账号密码，避免每次都输入：

macOS:

git config --global credential.helper osxkeychain

Linux:

git config --global credential.helper store

Windows:

git config --global credential.helper manager

2.2 针对不同仓库配置不同凭据

如果 GitHub 和 Gitea 使用不同的账号密码，可以在 .git/config 中配置：

# 编辑 Git 配置
vim .git/config

添加凭据辅助配置：

[credential "https://github.com"]
    username = chengchengzhou7

[credential "http://119.29.208.238:8080"]
    username = zhouchengcheng

三、日常操作

3.1 推送代码（自动双推）

推送当前分支到两个仓库：

git push

推送指定分支：

# 推送 dev 分支
git push origin dev

# 推送 main 分支
git push origin main

# 推送 release 分支
git push origin release

首次推送新分支需要设置上游：

git push -u origin <branch-name>

3.2 拉取代码（从 GitHub）

# 拉取当前分支
git pull

# 拉取指定分支
git pull origin dev
git pull origin main
git pull origin release

3.3 获取远程更新

# 获取所有远程分支的更新
git fetch origin

# 查看所有分支（包括远程）
git branch -a

四、分支管理

4.1 切换分支

# 切换到开发分支
git checkout dev

# 切换到主分支
git checkout main

# 切换到发布分支
git checkout release

4.2 创建新分支

# 基于 dev 创建新功能分支
git checkout -b feature/new-feature dev

# 推送到两个远程仓库
git push -u origin feature/new-feature

4.3 分支合并

# 将 dev 合并到 release
git checkout release
git merge dev
git push

# 将 release 合并到 main
git checkout main
git merge release
git push

五、常见问题

5.1 其中一个仓库推送失败怎么办？

如果双推时其中一个仓库失败，可以单独推送到失败的仓库：

# 单独推送到 GitHub
git push https://github.com/chengchengzhou7/CTMS.git dev

# 单独推送到 Gitea
git push http://119.29.208.238:8080/zhouchengcheng/ctms.git dev

5.2 如何只推送到一个仓库？

临时推送到指定仓库：

# 只推送到 GitHub
git push https://github.com/chengchengzhou7/CTMS.git

# 只推送到 Gitea
git push http://119.29.208.238:8080/zhouchengcheng/ctms.git

5.3 密码输入错误或需要更新

清除已保存的凭据：

# macOS
git credential-osxkeychain erase
host=github.com
protocol=https
[按两次回车]

# 或者使用
git credential reject
host=github.com
protocol=https
[按两次回车]

5.4 Gitea 首次推送需要创建仓库

如果 Gitea 仓库不存在，需要先在 Gitea 网页上创建空仓库：

访问 http://119.29.208.238:8080
登录后点击「新建仓库」
仓库名设置为 ctms
不要初始化 README
创建后再执行 git push

六、配置文件示例

当前项目的 .git/config 配置示例：

[core]
    repositoryformatversion = 0
    filemode = true
    bare = false
    logallrefupdates = true
    ignorecase = true
    precomposeunicode = true

[remote "origin"]
    url = https://github.com/chengchengzhou7/CTMS.git
    fetch = +refs/heads/*:refs/remotes/origin/*
    pushurl = https://github.com/chengchengzhou7/CTMS.git
    pushurl = http://119.29.208.238:8080/zhouchengcheng/ctms.git

[branch "main"]
    remote = origin
    merge = refs/heads/main

[branch "dev"]
    remote = origin
    merge = refs/heads/dev

[branch "release"]
    remote = origin
    merge = refs/heads/release

七、工作流建议

7.1 日常开发流程

# 1. 切换到 dev 分支
git checkout dev

# 2. 拉取最新代码
git pull

# 3. 创建功能分支
git checkout -b feature/xxx

# 4. 开发并提交
git add .
git commit -m "feat: 添加新功能"

# 5. 推送功能分支
git push -u origin feature/xxx

# 6. 合并到 dev（通过 PR 或直接合并）
git checkout dev
git merge feature/xxx
git push  # 自动推送到 GitHub 和 Gitea

7.2 发布流程

# 1. 将 dev 合并到 release
git checkout release
git pull
git merge dev
git push  # 双推到两个仓库

# 2. 测试通过后，合并到 main
git checkout main
git pull
git merge release
git push  # 双推到两个仓库

# 3. 打标签
git tag -a v1.0.0 -m "Release version 1.0.0"
git push origin v1.0.0  # 推送标签也会双推

最后更新: 2026-06-23
维护者: Cheng Zhou

13 KiB Raw Permalink Blame History Unescape Escape

Git 仓库同步与在线更新指南

第一部分：在线更新功能

功能特性

🔐 安全保障

✨ 易用性

快速开始

基础用法

认证方式

1. SSH 密钥（推荐，无需输入密码）

2. Personal Access Token（推荐用于 HTTPS）

3. 用户名密码（不推荐，安全性低）

命令选项

环境参数（必需）

可选参数

使用场景

场景 1：开发环境日常更新

场景 2：生产环境版本升级

场景 3：强制覆盖本地更改

场景 4：CI/CD 自动部署

故障排查

问题 1：认证失败

问题 2：项目身份验证失败

问题 3：合并冲突

问题 4：回滚到更新前版本

安全最佳实践

1. Personal Access Token 管理

2. 环境变量保护

3. 生产环境更新检查清单

常见问题

第二部分：双仓库推送配置

仓库信息

一、配置双推（同时推送到两个仓库）

1.1 查看当前配置

1.2 配置双推 URL

1.3 验证配置

二、账号密码管理

2.1 保存凭据（推荐）

2.2 针对不同仓库配置不同凭据

三、日常操作

3.1 推送代码（自动双推）

3.2 拉取代码（从 GitHub）

3.3 获取远程更新

四、分支管理

4.1 切换分支

4.2 创建新分支

4.3 分支合并

五、常见问题

5.1 其中一个仓库推送失败怎么办？

5.2 如何只推送到一个仓库？

5.3 密码输入错误或需要更新

5.4 Gitea 首次推送需要创建仓库

六、配置文件示例

七、工作流建议

7.1 日常开发流程

7.2 发布流程

13 KiB

Raw Permalink Blame History