124 lines
5.8 KiB
Markdown
124 lines
5.8 KiB
Markdown
# Git 自动同步 · 网页控制台（git-sync-web）
|
||
|
||
将 `git-auto-sync`（原 Bash 脚本版定时同步工具）的能力搬上网页：用浏览器即可监控、手动触发、查看差异、在线编辑文件、就地解决冲突，无需登录服务器敲命令行。
|
||
|
||
单二进制、纯标准库实现（Go 1.25+），前端资源通过 `go:embed` 内嵌，**零外部依赖、零运行时下载**，拷贝一个 exe 即可运行。
|
||
|
||
---
|
||
|
||
## 核心功能
|
||
|
||
### 1. 仓库总览（Dashboard）
|
||
- 每个被监控仓库一张卡片：同步状态灯、领先/落后提交数、本地改动文件数。
|
||
- 运行中的仓库实时显示；关闭「自动同步」的仓库标注「手动模式」徽标，仅响应手动触发。
|
||
- 顶部按钮「全部启动 / 全部暂停」一键管控。
|
||
|
||
### 2. 实时活动（SSE 日志）
|
||
- 右侧实时日志面板通过 Server-Sent Events 推送每个仓库的同步过程、提交、冲突等事件，并带错误/警告高亮。
|
||
- 支持按关键字过滤、一键清空。
|
||
|
||
### 3. 手动同步
|
||
- 每个仓库提供「获取 / 拉取 / 推送」按钮，随时手动触发，不必等待定时调度。
|
||
|
||
### 4. 差异查看（Diff）
|
||
- 支持「工作区 / 已暂存 / 某次提交」三种范围；统一视图与**并排（split）视图**切换。
|
||
- 可选的**词级差异**（`git --word-diff=plain`），改动以行内增删高亮呈现。
|
||
- 一键**复制**差异内容、下载 `.patch` 文件；编辑器内「对比此文件」可只看当前文件的改动。
|
||
|
||
### 5. 网页端文件编辑
|
||
- 文件树列出仓库内可跟踪 / 未跟踪文件，并标注改动状态（M/A/D/?）。
|
||
- 点击文件即可**在线读取与编辑**，保存可「仅写盘」或「保存并提交」。
|
||
- 内置 **CodeMirror** 语法高亮；编辑过程中自动缓存草稿到浏览器 `localStorage`，刷新不丢稿，可「放弃草稿」回滚。
|
||
- 二进制文件自动识别并只读提示。
|
||
|
||
### 6. 冲突解决
|
||
- **拉取冲突**：选择「放弃合并」或「我已在本地解决，继续」。
|
||
- **推送冲突**（non-fast-forward）：提供「强制推送（--force-with-lease）」或「放弃」。
|
||
- **冲突文件内联编辑**：直接在网页展开冲突文件、编辑解决、保存并标记已解决；所有冲突处理完毕时自动结束合并/变基。
|
||
|
||
### 7. 自动同步 / 自动提交 / Cron
|
||
- 每个仓库可设固定间隔（秒）或 **Cron 表达式**自动拉取推送（Cron 非空时优先于固定间隔）。
|
||
- 「自动提交」开启后，检测到工作区脏文件会自动 `add -A` + `commit` 再推送。
|
||
- 「自动同步」开关可单独关闭——关闭后该仓库不再自动运行，仅响应手动同步。
|
||
|
||
### 8. 提交历史
|
||
- 浏览仓库提交记录，点击展开单条提交的详细 diff。提交哈希经正则白名单校验，防止命令注入。
|
||
|
||
### 9. 统计
|
||
- 每次同步写入 CSV 统计（领先/落后/改动等），网页端以图表呈现近 30 天趋势。
|
||
|
||
### 10. 访问密码（可选）
|
||
- 启动时加 `-password` 参数启用鉴权：生成 30 天会话 cookie，除静态资源外的 API 均受保护。
|
||
|
||
---
|
||
|
||
## 编译与运行
|
||
|
||
```bash
|
||
# 编译（会重新内嵌 static 目录下的前端资源，改前端后必须重新 build）
|
||
go build -o git-auto.exe .
|
||
|
||
# Windows下可能需要执行如下命令编译：
|
||
go build -buildvcs=false -o git-auto.exe .
|
||
|
||
# 运行
|
||
./git-auto.exe -dir "C:/OtherFiles/Github/git-auto-sync" -addr 127.0.0.1:5757
|
||
```
|
||
|
||
| 参数 | 说明 | 默认值 |
|
||
| --- | --- | --- |
|
||
| `-dir` | 项目根目录，需包含 `configs/`、`logs/`、`stats/` | `.` |
|
||
| `-addr` | 监听地址 | `127.0.0.1:5757` |
|
||
| `-password` | 访问密码（为空则不启用鉴权） | 空 |
|
||
|
||
启动后浏览器打开 `http://127.0.0.1:5757` 即可。
|
||
|
||
---
|
||
|
||
## 配置文件格式
|
||
|
||
监控目标以 `.conf` 文件存放在 `-dir` 指定的 `configs/` 目录下，兼容原 Bash 脚本的配置字段：
|
||
|
||
```ini
|
||
# Git 自动同步配置 - 示例
|
||
REPO_PATH="/c/OtherFiles/Github/your-repo" # 支持 Git Bash 风格 /c/... 路径，会自动转为 Windows 路径
|
||
REMOTE_NAME="origin"
|
||
REMOTE_URL="https://example.com/you/repo.git"
|
||
# 多远程写法：REMOTES="origin=https://a.git,fork=https://b.git"
|
||
BRANCH="main"
|
||
MODE="both" # both / push / pull
|
||
INTERVAL="60" # 固定间隔（秒）
|
||
CRON="" # 可选，cron 表达式优先于 INTERVAL
|
||
LOG_FILE="/c/.../sync.log"
|
||
AUTH_METHOD="ssh" # ssh / https
|
||
AUTO_COMMIT="0" # 1 开启自动提交
|
||
AUTO_SYNC="1" # 0 关闭自动同步（仅手动）
|
||
CONFLICT_STRATEGY="merge" # merge / rebase
|
||
PUSH_STRATEGY="manual" # manual / auto
|
||
```
|
||
|
||
> 说明：路径既支持 `C:/...` 也支持 Git Bash 的 `/c/...`，后者会在加载时自动规范化；`.git` 内部目录被禁止通过网页访问。
|
||
|
||
---
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
git-sync-web/
|
||
├── main.go # 入口：-dir / -addr / -password，内嵌 static
|
||
├── config.go # .conf 解析与写回、Windows 路径规范化
|
||
├── git.go # git 执行器、领先/落后、冲突检测
|
||
├── engine.go # 每仓库调度循环、SSE 事件总线、文件树/读写
|
||
├── cron.go # 纯标准库 5 段 cron 解析（含单测）
|
||
├── server.go # REST API 与静态资源服务
|
||
└── static/ # 前端：index.html / app.js / style.css / cm-boot.js / vendor/cm/
|
||
```
|
||
|
||
---
|
||
|
||
## 设计要点
|
||
|
||
- **单二进制 + 内嵌前端**：部署只需一个可执行文件，不依赖任何外部 CDN 或运行时。
|
||
- **安全边界**：仓库内路径经 `safeRepoPath` 严格校验，禁止 `..` 越界与访问 `.git`；提交哈希白名单防注入；网页编辑单文件 ≤1MB 且拒绝二进制写入。
|
||
- **优雅降级**：CodeMirror 资源缺失或初始化失败时，编辑器自动回退原生 `<textarea>`，核心功能不受影响。
|