# Git Gogs 完整操作手册

> Gogs 服务器: https://git.zhonjin.com:40717  
> 用户: steven_roc  
> 最后更新: 2026-10-08

---

## 一、当前所有仓库总览

| 仓库 | 说明 | 大小 | 最近更新 |
|------|------|------|----------|
| git_gog_code_sync | Git Gogs 代码自动同步方案 | 28 MB | 2026-10-08 |
| hikvision-isup-client | 海康 ISUP 客户端 C 项目 | 372 MB | 2026-10-08 |
| dts_monitor_android | DTS 光纤温度监控 Android 客户端 | 348 MB | 2026-10-07 |
| mppt_monitor | MPPT 监控 | 34.6 GB | 2026-10-07 |
| mppt_monitor_android | MPPT 监控 Android 客户端 | 248 MB | 2026-10-07 |
| android-client | 宝林电厂环流监控 Android 客户端 | 160 MB | 2026-10-07 |
| md5-keygen | CPU序列号MD5密钥 Web 服务 | 1.08 GB | 2026-10-07 |
| md5-keygen-android | CPU序列号MD5密钥 Android App | 104 MB | 2026-10-07 |
| nginx-stream-ssl-preread | Nginx Stream + SSL Preread 分流 | 80 MB | 2026-10-06 |
| PlateRecApp | 车牌识别系统 | 483 MB | 2026-10-05 |
| current-monitor | 宝林电厂环流监控系统 | 7.6 GB | 2026-10-05 |
| dts_monitor | DTS 分布式光纤温度传感器监控 | 180 MB | 2026-10-05 |

---

## 二、Gogs Web 界面完整操作指南

### 2.1 访问仓库主页

浏览器打开：`https://git.zhonjin.com:40717/steven_roc/<仓库名>`

例如：
- https://git.zhonjin.com:40717/steven_roc/git_gog_code_sync
- https://git.zhonjin.com:40717/steven_roc/PlateRecApp

### 2.2 查看所有提交历史

**路径**: 仓库页面 → 点击 **「提交数」** 或 **「Commits」** 链接

URL 格式：
```
https://git.zhonjin.com:40717/steven_roc/<仓库名>/commits/master
```

**操作说明**：
- 每一条提交显示：提交信息、SHA（前8位）、提交时间、作者
- 点击 **SHA 编号** → 查看该次提交的完整 diff（改了哪些文件的哪些行）
- 点击 **提交信息** → 查看该次提交的详情
- 点击 **浏览代码** → 查看该次提交时的完整文件快照（🔑 这就是查看上一次版本的方法）

### 2.3 🔑 查看上一次版本的完整内容

**方法 A：通过提交历史回退查看**

1. 进入仓库页面 → 点击 **「提交数」**
2. 找到你想查看的那次提交（比如上一次推送）
3. 点击该提交右侧的 **「<>」浏览代码按钮**
4. 此时看到的就是该次提交时的完整文件列表和内容

**方法 B：通过切换标签/分支查看**

如果有打 Tag：
1. 仓库页面 → 点击 **「标签」** 或 **「Tags」**
2. 点击具体标签名 → 查看该版本的完整代码

**方法 C：通过 URL 直接访问指定版本**

```
# 查看指定 commit 时的文件列表
https://git.zhonjin.com:40717/steven_roc/<仓库名>/src/<commit_sha>

# 查看指定 commit 时的某个文件
https://git.zhonjin.com:40717/steven_roc/<仓库名>/src/<commit_sha>/<文件路径>
```

**方法 D：对比两个版本之间的差异**

```
# 对比两次提交的差异
https://git.zhonjin.com:40717/steven_roc/<仓库名>/compare/<旧commit_sha>...<新commit_sha>
```

### 2.4 在 Web 上查看单个文件

```
# 查看文件内容（带语法高亮）
https://git.zhonjin.com:40717/steven_roc/<仓库名>/src/master/<文件路径>

# 查看文件原始内容（纯文本，可直接复制）
https://git.zhonjin.com:40717/steven_roc/<仓库名>/raw/master/<文件路径>

# 查看文件的提交历史（这个文件被改了哪几次）
https://git.zhonjin.com:40717/steven_roc/<仓库名>/commits/master/<文件路径>

# 查看某个文件在某个版本的内容
https://git.zhonjin.com:40717/steven_roc/<仓库名>/raw/<commit_sha>/<文件路径>
```

### 2.5 在 Web 上下载代码

| 下载方式 | 操作 |
|----------|------|
| **ZIP 归档** | 仓库页 → 点击 **「克隆/下载」** → **「下载 ZIP」** |
| **指定版本 ZIP** | 仓库页 → **「提交数」** → 某次提交 → **「<>」** → **「下载 ZIP」** |
| **指定分支/标签** | 仓库页 → 分支选择器切换到目标分支/标签 → **「下载 ZIP」** |

直接下载链接：
```
# 最新 master 分支
https://git.zhonjin.com:40717/steven_roc/<仓库名>/archive/master.zip

# 指定 commit
https://git.zhonjin.com:40717/steven_roc/<仓库名>/archive/<commit_sha>.zip
```

### 2.6 Web 界面功能速查

| 功能 | 入口 |
|------|------|
| 📁 浏览文件 | 仓库主页 |
| 📝 查看提交历史 | **「提交数」** 链接 |
| 🔍 搜索代码 | 仓库页搜索框 |
| 📊 查看文件修改历史 | 文件页 → **「历史」** |
| 🔀 查看分支列表 | **「分支」** 下拉菜单 |
| 🏷️ 查看标签/版本 | **「标签」** 链接 |
| 📥 下载归档 | **「克隆/下载」** → **「下载 ZIP」** |
| ⚙️ 仓库设置 | **「设置」** 选项卡 |

---

## 三、Git 命令行完整操作

### 3.1 首次克隆

```bash
# HTTPS 克隆
git clone https://git.zhonjin.com:40717/steven_roc/<仓库名>.git
cd <仓库名>

# SSH 克隆（需先配置 SSH Key）
git clone git@git.zhonjin.com:steven_roc/<仓库名>.git

# 浅克隆（只拉最新一次提交，速度快）
git clone --depth 1 https://git.zhonjin.com:40717/steven_roc/<仓库名>.git
```

### 3.2 查看历史版本

```bash
# 查看提交历史
git log --oneline

# 查看某个 commit 的详细改动
git show <commit_sha>

# 查看某个 commit 时的某个文件内容
git show <commit_sha>:<文件路径>

# 回退到上一个版本（保留改动在工作区）
git reset --soft HEAD~1

# 回退到上一个版本（彻底丢弃改动）
git reset --hard HEAD~1

# 切换到某个历史版本查看（不改变当前分支）
git checkout <commit_sha>

# 回到最新
git checkout master
```

### 3.3 日常修改推送

```bash
# 1. 拉取最新代码
git pull origin master

# 2. 查看改了什么
git status
git diff

# 3. 添加并提交
git add -A
git commit -m "描述你改了什么"

# 4. 推送到 Gogs
git push origin master
```

### 3.4 分支管理

```bash
# 创建并切换到新分支
git checkout -b feature-xxx

# 推送新分支到远程
git push -u origin feature-xxx

# 合并分支到 master
git checkout master
git merge feature-xxx

# 删除远程分支
git push origin --delete feature-xxx
```

### 3.5 标签管理（版本发布）

```bash
# 创建标签
git tag -a v1.0.0 -m "版本 1.0.0 发布"

# 推送标签到 Gogs
git push origin v1.0.0

# 推送所有标签
git push origin --tags

# 查看所有标签
git tag -l

# 切换到某个标签
git checkout v1.0.0
```

---

## 四、Gogs API 完整参考

### 4.1 认证方式

所有 API 请求都需要 Access Token：
```bash
# Header 方式（推荐）
curl -H "Authorization: token <你的Access_Token>" <URL>

# URL 参数方式
curl "<URL>?token=<你的Access_Token>"
```

### 4.2 仓库相关 API

```bash
BASE="https://git.zhonjin.com:40717/api/v1"

# 列出所有仓库
curl -sk -H "Authorization: token $TOKEN" "$BASE/user/repos"

# 创建仓库
curl -sk -X POST -H "Authorization: token $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"新仓库名","description":"描述","private":false}' \
  "$BASE/user/repos"

# 获取仓库信息
curl -sk -H "Authorization: token $TOKEN" "$BASE/repos/steven_roc/<仓库名>"

# 删除仓库
curl -sk -X DELETE -H "Authorization: token $TOKEN" "$BASE/repos/steven_roc/<仓库名>"
```

### 4.3 文件相关 API

```bash
# 获取目录文件列表
curl -sk -H "Authorization: token $TOKEN" \
  "$BASE/repos/steven_roc/<仓库名>/contents/"

# 获取文件内容（base64 编码）
curl -sk -H "Authorization: token $TOKEN" \
  "$BASE/repos/steven_roc/<仓库名>/contents/README.md"

# 获取文件原始内容（纯文本）
curl -sk -H "Authorization: token $TOKEN" \
  "https://git.zhonjin.com:40717/steven_roc/<仓库名>/raw/master/README.md"

# 创建/更新文件
curl -sk -X PUT -H "Authorization: token $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "message": "update README",
    "content": "'$(base64 -w0 README.md)'"
  }' \
  "$BASE/repos/steven_roc/<仓库名>/contents/README.md"

# 删除文件
curl -sk -X DELETE -H "Authorization: token $TOKEN" -H "Content-Type: application/json" \
  -d '{"message":"delete file","sha":"<文件sha>"}' \
  "$BASE/repos/steven_roc/<仓库名>/contents/<文件路径>"
```

### 4.4 提交历史 API

```bash
# 查看提交列表
curl -sk -H "Authorization: token $TOKEN" \
  "$BASE/repos/steven_roc/<仓库名>/commits?sha=master&limit=10"

# 查看单个提交详情
curl -sk -H "Authorization: token $TOKEN" \
  "$BASE/repos/steven_roc/<仓库名>/git/commits/<commit_sha>"

# 查看某个提交的 diff
curl -sk -H "Authorization: token $TOKEN" \
  "$BASE/repos/steven_roc/<仓库名>/commits/<commit_sha>/diff"
```

### 4.5 分支与标签 API

```bash
# 查看所有分支
curl -sk -H "Authorization: token $TOKEN" \
  "$BASE/repos/steven_roc/<仓库名>/branches"

# 查看所有标签
curl -sk -H "Authorization: token $TOKEN" \
  "$BASE/repos/steven_roc/<仓库名>/tags"

# 创建标签
curl -sk -X POST -H "Authorization: token $TOKEN" -H "Content-Type: application/json" \
  -d '{"tag_name":"v1.0.0","message":"版本1.0","target":"master"}' \
  "$BASE/repos/steven_roc/<仓库名>/tags"
```

### 4.6 下载归档 API

```bash
# 下载指定分支 ZIP
curl -sk -H "Authorization: token $TOKEN" \
  -o repo.zip \
  "https://git.zhonjin.com:40717/steven_roc/<仓库名>/archive/master.zip"

# 下载指定标签 ZIP
curl -sk -H "Authorization: token $TOKEN" \
  -o repo-v1.zip \
  "https://git.zhonjin.com:40717/steven_roc/<仓库名>/archive/v1.0.0.zip"

# 下载指定 commit ZIP
curl -sk -H "Authorization: token $TOKEN" \
  -o repo-specific.zip \
  "https://git.zhonjin.com:40717/steven_roc/<仓库名>/archive/<commit_sha>.zip"
```

---

## 五、自动同步脚本（生产级）

### 5.1 完整推送脚本

```bash
#!/bin/bash
# git_gogs_push.sh - 完整推送脚本
# 用法: ./git_gogs_push.sh [提交说明]

set -euo pipefail

COMMIT_MSG="${1:-auto sync: $(date '+%Y-%m-%d %H:%M:%S')}"
GOGS_URL="https://git.zhonjin.com:40717"
REPO_DIR="$(cd "$(dirname "$0")" && pwd)"

cd "$REPO_DIR"

# 检查是否有变更
if [[ -z "$(git status --porcelain)" ]]; then
    echo "✅ 没有变更，跳过推送"
    exit 0
fi

# 显示变更内容
echo "📋 检测到以下变更："
git status --short

# 添加、提交、推送
git add -A
git commit -m "$COMMIT_MSG"
git push origin master

echo "✅ 推送完成: $COMMIT_MSG"
echo "🔗 仓库: $GOGS_URL/steven_roc/$(basename "$REPO_DIR")"
```

### 5.2 完整拉取脚本

```bash
#!/bin/bash
# git_gogs_pull.sh - 完整拉取脚本
# 用法: ./git_gogs_pull.sh

set -euo pipefail

REPO_DIR="$(cd "$(dirname "$0")" && pwd)"
cd "$REPO_DIR"

echo "📥 拉取最新代码..."
git pull --rebase origin master

echo ""
echo "📋 最近 5 次提交："
git log --oneline -5

echo ""
echo "📁 当前文件："
ls -la
```

### 5.3 一键备份全部仓库脚本

```bash
#!/bin/bash
# gogs_backup_all.sh - 备份 Gogs 上所有仓库
# 用法: ./gogs_backup_all.sh [备份目录]

set -euo pipefail

TOKEN="你的Access_Token"
GOGS_URL="https://git.zhonjin.com:40717"
BACKUP_DIR="${1:-./gogs_backup_$(date '+%Y%m%d')}"
API="$GOGS_URL/api/v1"

mkdir -p "$BACKUP_DIR"

echo "📦 开始备份所有仓库到 $BACKUP_DIR"

# 获取所有仓库
repos=$(curl -sk -H "Authorization: token $TOKEN" "$API/user/repos" | \
    python3 -c "import sys,json; [print(r['name']) for r in json.loads(sys.stdin.read())]")

for repo in $repos; do
    echo "  📥 正在备份: $repo"
    curl -sk -H "Authorization: token $TOKEN" \
        -o "$BACKUP_DIR/${repo}.zip" \
        "$GOGS_URL/steven_roc/$repo/archive/master.zip"
done

echo ""
echo "✅ 备份完成！共 $(echo "$repos" | wc -l) 个仓库"
echo "📁 备份目录: $BACKUP_DIR"
ls -lh "$BACKUP_DIR"
```

---

## 六、SSH Key 配置

```bash
# 1. 生成密钥
ssh-keygen -t ed25519 -C "steven_roc@zhonjin.com"

# 2. 查看公钥
cat ~/.ssh/id_ed25519.pub

# 3. 添加到 Gogs
# 登录 → 右上角头像 → 设置 → SSH 密钥 → 添加密钥

# 4. 配置 SSH config（免端口参数）
cat >> ~/.ssh/config << 'EOF'
Host git.zhonjin.com
    HostName git.zhonjin.com
    Port 40717
    User git
    IdentityFile ~/.ssh/id_ed25519
    StrictHostKeyChecking no
EOF

# 5. 测试连接
ssh -T -p 40717 git@git.zhonjin.com
```

---

## 七、常见问题排查

| 问题 | 原因 | 解决方案 |
|------|------|----------|
| SSL 证书错误 | 自签名证书 | `GIT_SSL_NO_VERIFY=true` 或 `git config http.sslVerify false` |
| 401 Unauthorized | Token 过期 | Gogs 设置 → 应用 → 重新生成 Token |
| push 被拒绝 | 远程有更新 | 先 `git pull --rebase` 再 push |
| 中文文件名乱码 | 编码问题 | `git config core.quotepath false` |
| 大文件推送超时 | 文件太大 | 使用 `git lfs` 或分批推送 |
| 忘记 Token | 安全原因无法找回 | 重新生成新 Token |

---

*本手册覆盖 Git Gogs 的完整操作：Web 界面、命令行、API、自动同步脚本、备份方案。*