0 Fork 0

Files

T

guzhujushi bcdbdd35a3 docs: 记录 Gitea 远端接入方式

- STATUS.md：Gitea 接入标记完成，补充远端/分支/推送通道信息；
  新增决策 19（SSH 走 Tailscale 内网）与 20（首次推送 force-with-lease 的取舍）
- docs/05-git-workflow.md：第三节改写为实际拓扑（公网 22 被过滤、
  走 Tailscale + ~/.ssh/config 域名别名），补自检、日常推送、换机步骤，
  并保留仓库归属注意、补充可见性与协作者说明；
  回滚一节记录被覆盖提交的恢复命令

2026-10-01 17:56:12 +08:00

5.6 KiB

Raw Blame History

Git 工作流与远程托管

本仓库已初始化：分支 main，首次提交 5319589（76 文件），工作区干净。尚未配置远程，之后托管到你自己的 Gitea。

一、仓库约定

行尾

由 .gitattributes 强制：仓库内一律 LF，checkout 时不做自动转换。

原因：AGENTS.md 要求 shell 脚本 UTF-8 无 BOM + LF；而这个仓库会被队友在 Windows / WSL / Linux 上 clone。不固定行尾的话，每次提交都会出现 "整个文件都变了"的假 diff，review 时根本看不出真实改动。

例外：*.bat / *.cmd 保持 CRLF（cmd 解析需要）。

Windows 用户建议同时设：

git config --global core.autocrlf false
git config --global core.eol lf

什么不入库

见 .gitignore。重点是三条：

忽略	为什么
`.venv/`、`.conda/`	环境可由 `scripts/setup-*.ps1` 重建，不该进版本库
`problems//raw/`、`/.xlsx`、`problems//.csv`	赛题原始数据体积大、可重新下载；只提交处理脚本和结论
`figures/.png`、`figures/.pdf`、`tables/*.csv`	中间产物。定稿的图请放进 `problems/<年份>_<题号>/figures/` 再提交

判断标准：这个东西能不能由仓库里的其他文件重新生成？ 能 → 不入库。

二、日常提交

git add -A
git commit -m "feat(stats): 实现 bootstrap_ci"

提交信息建议带模块前缀，方便以后回溯"这个函数是哪次加的"：

前缀	用途
`feat(<模块>)`	新增函数 / 功能
`fix(<模块>)`	修 bug
`test(<模块>)`	只改测试
`docs`	只改文档
`env`	环境、依赖、脚本
`chore`	其他杂项

提交前跑一遍：

.\scripts\doctor.ps1

它会同时检查 venv 和 conda 两套环境并跑测试。

三、远程托管（已配置）

项	值
Gitea 网页	https://code.guzhujushi.cn/guzhujushi/MCM-ICM_Toolkit
服务器公网 IP	`8.145.36.108`（实测只开了 443，22 被防火墙过滤）
服务器 Tailscale IP	`100.115.86.48`（22 开放）
本机 Tailscale IP	`100.124.243.30`
git 远端	`git@code.guzhujushi.cn:guzhujushi/MCM-ICM_Toolkit.git`

为什么走 Tailscale

公网 22 端口连不上（ssh: connect to host code.guzhujushi.cn port 22: Connection timed out），但同一台机器的 Tailscale 地址 22 端口是通的，且 git@ 认证直接通过 Gitea。所以 ~/.ssh/config 里加了一条别名把域名指到内网地址：

Host code.guzhujushi.cn
  HostName 100.115.86.48
  User git
  IdentityFile ~/.ssh/id_ed25519

这样 remote 里写的是域名，换机时只改这一段 config，不用动仓库配置。

推送前先连上 Tailscale，否则 git push 会一直等到超时。

自检

ssh -T git@code.guzhujushi.cn
# 期望输出：Hi there, guzhujushi! You've successfully authenticated with the key named ...

日常推送

cd D:\MCM&ICM_Toolkit
git add -A
git commit -m "feat(stats): 实现 bootstrap_ci"
git push

换一台机器 / 加一个协作者

# 1) 装 Tailscale 并加入同一个 tailnet
# 2) 生成并上传密钥
ssh-keygen -t ed25519 -C "your@email"
Get-Content "$env:USERPROFILE\.ssh\id_ed25519.pub" | Set-Clipboard
#    粘贴到 Gitea → 设置 → SSH/GPG 密钥
# 3) 写上面的 ~/.ssh/config 别名
# 4) 克隆
git clone git@code.guzhujushi.cn:guzhujushi/MCM-ICM_Toolkit.git

不想用 Tailscale 的话，也可以用 HTTPS + Gitea 访问令牌，代价是每次推送要输凭据（或交给凭据助手缓存）：

git remote add origin https://code.guzhujushi.cn/guzhujushi/MCM-ICM_Toolkit.git

注意：git config --global http.proxy 目前指向 UniClash（127.0.0.1:7993）， HTTPS 方式会被代理绕一圈；SSH 方式不受该配置影响。

仓库归属注意（重要）

.git 必须是你自己的账户创建的。若用沙箱化的 AI agent 通道代跑 git init，它可能以别的账户身份创建 .git，之后你自己跑 git 就会报：

fatal: detected dubious ownership in repository

正确做法是删掉重建（以本人账户）：

Remove-Item -LiteralPath .git -Recurse -Force
git init -b main

不要用 git config --global --add safe.directory 绕过——那只是把问题藏起来，而且会让 git 在真正的归属异常时也不再警告。

同理，沙箱通道写出的文件 Owner 会是沙箱账户，但权限继承自 Authenticated Users（Modify），读写不受影响，只有 git 的归属检查会误报。

可见性与协作者

匿名 git ls-remote 实测可读 → 仓库当前是 Public。要改私有：仓库设置 → 基本设置 → 可见性。加队友：仓库设置 → 协作者 → 添加成员。

四、给队友的说明

队友 clone 后只需要：

git clone <你的仓库地址>
cd mcm-icm-toolkit
.\scripts\setup-venv.ps1      # 零下载，复用他们自己的 Anaconda base
.\scripts\doctor.ps1

setup-venv.ps1 用的是 --system-site-packages，所以他们本机得先有 Anaconda。如果队友没有 Anaconda，让他走 scripts/setup-conda.ps1。

五、回滚

环境升级出问题时的回退手段：

# 远端被覆盖过一次（首次推送），那个提交仍在本机对象库里：
# git push origin 1c683cf:refs/heads/restore-initial

# conda 自己保留了 revision 历史
conda list -n base --revisions
conda install -n base --revision <N>

# 代码回滚
git log --oneline
git revert <commit>

5.6 KiB Raw Blame History Unescape Escape