Gitea 配置 GitHub 代理与镜像同步指南
本文档覆盖两个核心场景：
- Gitea 通过代理访问 GitHub（解决 Gitea 服务器无法直接连通 GitHub 的问题）
- Gitea 仓库改动自动同步到 GitHub（Push Mirror，Gitea 为主仓库）
一、Gitea 通过代理访问 GitHub
1.1 适用场景
Gitea 部署在内网或网络受限环境，无法直接 clone/pull GitHub 仓库，需要走代理（如 Clash、V2Ray 等本地代理工具）中转。
1.2 修改 app.ini 配置
找到 Gitea 配置文件 app.ini（路径通常为 /opt/gitea/custom/conf/app.ini 或 Docker 挂载目录下的 custom/conf/app.ini），添加以下配置：
[proxy]
PROXY_ENABLED = true
PROXY_URL = http://127.0.0.1:7890
PROXY_HOSTS = *.github.com,*.githubusercontent.com
[migrations]
ALLOW_LOCALNETWORKS = true
配置项说明：
| 配置项 | 说明 |
|---|---|
PROXY_ENABLED | 是否开启代理，设为 true |
PROXY_URL | 代理地址，支持 http://、https://、socks5:// 协议。根据实际代理工具填写端口（Clash 默认 7890，V2Ray 默认 1087 等） |
PROXY_HOSTS | 需要走代理的域名，支持通配符 *，多个域名用英文逗号分隔 |
ALLOW_LOCALNETWORKS | 代理地址为 127.0.0.1 或局域网地址时必须设为 true，否则 Gitea 会因安全校验拒绝访问 |
1.3 重启 Gitea 使配置生效
# 二进制安装
systemctl restart gitea
# Docker / Podman
docker restart gitea
# 或
podman restart gitea
1.4 验证代理是否生效
进入 Gitea 容器测试：
# 进容器
podman exec -it gitea bash
# 测试能否访问 GitHub
curl -I https://github.com
# 测试能否 clone（走代理）
cd /tmp && git clone https://github.com/gitea/awesome-gitea.git test-repo
如果 curl 返回 200 且 git clone 成功，说明代理配置生效。
1.5 Podman 网络注意事项
Podman 默认以 rootless 模式运行，使用 slirp4netns 做用户态网络隔离，默认不转发 ICMP（ping 不通是正常现象），但 TCP 流量（curl、git、wget）不受影响。
如果 Gitea 容器需要直接访问宿主机代理，推荐两种方案：
方案 A：使用 host 网络（推荐）
podman run -d \
--name gitea \
--replace \
--network host \
-v $(pwd)/gitea-data:/data \
gitea/gitea:latest
使用
--network host后需删除-p端口映射参数，因为 host 模式下端口直接绑定宿主机。
方案 B：保留桥接网络，代理地址改用宿主机网关 IP
在容器内执行 ip route 查看网关地址（通常为 10.0.2.2），将 app.ini 中的 PROXY_URL 改为：
PROXY_URL = http://10.0.2.2:7890
二、Gitea 仓库同步到 GitHub（Push Mirror）
2.1 整体思路
开发者 → push → Gitea（主仓库） → 自动 push → GitHub（镜像仓库）
Gitea 作为主仓库接收所有提交，配置 Push Mirror 后，每次推送到 Gitea 会自动同步到 GitHub。
2.2 在 GitHub 侧准备
- 登录 GitHub → 右上角头像 → Settings → Developer settings → Personal access tokens → Tokens (classic)
- 点 Generate new token (classic)，名称随意（如
gitea-push） - 勾选权限：
- 公开仓库：勾选
public_repo - 私有仓库：勾选
repo（全选下属项） - 使用 GitHub Actions：额外勾选
workflow
- 公开仓库：勾选
- 点 Generate token，复制保存（只显示一次）
⚠️ GitHub 不支持通过推送自动创建仓库，必须先在 GitHub 上手动创建一个同名空仓库（不要初始化 README / License，保持完全空）。
2.3 在 Gitea 配置 Push Mirror
- 进入 Gitea 对应仓库 → Settings（设置） → Repository（仓库）
- 滚动到 Mirror Settings（镜像设置） 区域
- Git Remote Repository URL 填写：
https://github.com/你的GitHub用户名/仓库名.git - 展开 Authorization（授权）：
- Username：填你的 GitHub 用户名
- Password：填刚才生成的 GitHub PAT（Token）
- ✅ 勾选 Sync when new commits are pushed（推送新提交时同步）
- Mirror Interval 可按需设置（如
8h），有"推送时同步"后不依赖定时 - 点 Add Push Mirror（添加推送镜像）
- 保存后点 Synchronize Now（立即同步） 测试
2.4 验证同步是否生效
# 本地推送到 Gitea
git push gitea main
# 等待几秒后访问 GitHub 仓库页面
# 确认代码已自动出现
也可在 Gitea 仓库 → Settings → Mirror Settings 查看最近同步状态和报错信息。
2.5 Push Mirror 工作原理说明
- Push Mirror 底层执行的是
git push --force --mirror - 会覆盖 GitHub 远端所有分支和标签
- 不要在 GitHub 侧直接修改代码，否则会被下一次同步冲掉
- 适合单向同步场景：Gitea 写 → GitHub 只读展示/备份
三、完整流程图
┌──────────┐ push ┌──────────────┐ auto push ┌──────────┐
│ Developer │ ───────────▶ │ Gitea │ ──────────────▶ │ GitHub │
│ (本地) │ │ (主仓库+代理) │ (Push Mirror) │ (镜像仓库)│
└──────────┘ └──────────────┘ └──────────┘
│
│ 通过代理访问
▼
┌──────────────┐
│ Proxy │
│ (Clash/V2Ray)│
└──────────────┘
四、常见问题排查
| 问题 | 原因与对策 |
|---|---|
| 迁移/同步报 403 | PAT 权限不够（没勾 repo/public_repo），重新生成 Token |
| 同步失败 / 连接超时 | Gitea 无法访问 GitHub，检查 app.ini 代理配置 + 宿主机代理是否运行 |
| 添加镜像报认证失败 | Token 复制不全或已过期，重新生成并粘贴 |
| GitHub 仓库已有内容导致冲突 | 必须确保 GitHub 仓库是空的（无初始提交），删除重建 |
| Podman 容器内无法访问宿主机代理 | 改用 --network host 或把代理地址改为容器网关 IP |
| 同步成功但 GitHub 显示无内容 | 检查 Gitea 仓库是否有实际提交（空仓库不会同步任何内容） |
| 想批量配置多个仓库的 Push Mirror | 使用 Gitea API：POST /api/v1/repos/{owner}/{repo}/push_mirrors |
五、Gitea API 批量创建 Push Mirror（可选）
如果需要给多个仓库一次性挂上 Push Mirror，可以用 curl 调用 Gitea API：
#!/bin/bash
GITEA_URL="http://localhost:3000"
GITEA_TOKEN="你的Gitea管理员Token"
GITHUB_USER="你的GitHub用户名"
GITHUB_TOKEN="你的GitHub PAT"
# 仓库列表
repos=("repo1" "repo2" "repo3")
for repo in "${repos[@]}"; do
curl -X POST \
"$GITEA_URL/api/v1/repos/你的Gitea用户名/$repo/push_mirrors" \
-H "Authorization: token $GITEA_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"remote_name": "github",
"remote_url": "https://github.com/'"$GITHUB_USER"'/'"$repo"'.git",
"username": "'"$GITHUB_USER"'",
"password": "'"$GITHUB_TOKEN"'",
"sync_on_commit": true,
"interval": "8h"
}'
echo ""
echo "✅ $repo mirror configured"
done
将脚本保存为 batch-mirror.sh，修改顶部变量后执行：
chmod +x batch-mirror.sh
./batch-mirror.sh
⚠️ 执行前确保 GitHub 上已创建好对应的空仓库，否则同步会失败。
六、参考链接
- Gitea 官方文档 - 代理配置：https://docs.gitea.com/administration/config-cheat-sheet#proxy
- Gitea 官方文档 - 仓库镜像：https://docs.gitea.com/usage/repo-mirror
- Gitea API 文档 - Push Mirrors：https://try.gitea.io/api/swagger#/repository/createPushMirror
- GitHub PAT 创建：https://github.com/settings/tokens