github项目更新维护手册

本文用于日常手动更新代码与服务。

适用场景

• 你已经通过 git clone 拉取过本仓库。

• 你希望把本地仓库更新到远端最新 main。

一、更新前检查

在项目目录执行：

 cd <项目文件夹>
 git status
 git branch --show-current
 git remote -v

预期：

• 当前分支是 main

• 远程地址包含 https://github.com/xxx/xxx

二、标准更新（无本地改动）

 git switch main
 git pull --ff-only origin main

说明：

• --ff-only 只允许快进更新，避免自动产生 merge commit。

三、有本地改动时的更新

先执行：

 git status

方案 A：你要保留并提交改动（推荐）

 git add -A
 git commit -m "wip: local changes before update"
 git pull --ff-only origin main

方案 B：你只想临时收起改动

 git stash push -u -m "temp-before-pull"
 git pull --ff-only origin main
 git stash pop

如果 git stash pop 出现冲突，按冲突提示手动解决后再提交。

四、更新后验证

 git status
 git log --oneline -n 5

可选：启动服务做一次功能检查

 uv run main.py

五、Docker Compose 部署的更新

如果你使用 docker compose 部署，代码更新后执行：

 docker compose pull
 docker compose up -d
 docker compose ps

如果你使用本地源码构建镜像：

 docker compose build --no-cache
 docker compose up -d

六、常见问题

1）Failed to connect to github.com port 443

原因通常是网络不可达、代理未配置或被防火墙拦截。 处理建议：

• 检查本机是否可访问 GitHub

• 配置或切换网络代理

• 稍后重试 git pull --ff-only origin main

2）fatal: not possible to fast-forward

表示本地分支历史与远端出现分叉。可先拉取并查看差异：

 git fetch origin
 git log --oneline --graph --decorate --all -n 30

再决定是 rebase 还是 merge（按你的团队规范执行）。

七、推荐日常更新命令（最简版）

 cd E:\xxx
 git switch main
 git pull --ff-only origin main
 git status