llm_wiki/wiki/Gitea-故障排查.md

categories, tags, created, source, type, aliases

categories	tags	created	source	type	aliases
LLM Wiki	wiki troubleshooting git gitea	2026-04-07	Gitea个人Git服务部署指南	concept	Gitea 问题排查 Git 推送失败

Gitea 故障排查

经验总结：首次使用 Gitea 推送 Obsidian vault（685 文件，140MB）时遇到的5个典型问题及解决方案

问题概览

问题	错误信息	根本原因	解决难度
1. .git/config 损坏	bad config line 1 in file .git/config	写入操作失败	⭐ 简单
2. 代理连接失败	Failed to connect to git.haiguang.xyz port 443	HTTP 代理配置	⭐⭐ 中等
3. 仓库路径错误	repository not found	用户名/仓库名错误	⭐ 简单
4. 分支名不匹配	src refspec main does not match any	本地/远程分支名不一致	⭐ 简单
5. HTTP 413 错误	HTTP 413 curl 22	服务器上传大小限制	⭐⭐⭐⭐ 复杂

---

问题 1：.git/config 文件损坏

错误表现

git status
fatal: bad config line 1 in file .git/config

问题场景

在尝试通过脚本或程序更新 Git 配置后，配置文件被错误覆盖：

# 损坏的内容（垃圾文本）
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

根本原因

1. 写入错误：程序以错误模式打开文件（二进制而非文本）
2. 并发冲突：多个进程同时写入
3. 权限问题：文件权限不足导致写入失败
4. 手动编辑错误：直接编辑配置文件时格式错误

解决方案

步骤 1：备份并删除损坏文件

# 备份（可选）
cp .git/config .git/config.backup

# 删除损坏文件
rm .git/config

步骤 2：重新初始化 Git 配置

# 设置用户信息
git config user.name "Your Name"
git config user.email "your@email.com"

# 验证配置
cat .git/config

步骤 3：重新添加远程仓库

# 删除旧的远程配置（如果存在）
git remote remove origin

# 添加正确的远程地址
git remote add origin https://git.haiguang.xyz/username/repo.git

# 验证
git remote -v

步骤 4：手动编辑配置文件（高级）

如果需要更精细的控制，可以手动编辑 .git/config：

[core]
    repositoryformatversion = 0
    filemode = false
    bare = false
    logallrefupdates = true
    symlinks = false
    ignorecase = true

[user]
    name = Your Name
    email = your@email.com

[remote "origin"]
    url = https://git.haiguang.xyz/username/repo.git
    fetch = +refs/heads/*:refs/remotes/origin/*

预防措施

# 使用 Git 命令而非直接编辑
git config --local user.name "Your Name"

# 或使用 --file 参数指定路径
git config --file .git/config user.email "your@email.com"

# 验证配置格式
git config --list --local

---

问题 2：代理连接失败

错误表现

git push
fatal: unable to access 'https://git.haiguang.xyz/.../':
Failed to connect to git.haiguang.xyz port 443 via 127.0.0.1:7890

问题场景

系统配置了 HTTP 代理（http://127.0.0.1:7890），但 Git 推送时无法通过代理连接。

根本原因

1. 代理配置错误：代理地址或端口不正确
2. 代理服务未运行：代理程序未启动
3. 防火墙限制：防火墙阻止代理连接
4. VPN 冲突：VPN 和代理配置冲突

解决方案

方案 1：清除代理设置（推荐）

# 清除全局代理
git config --global --unset http.proxy
git config --global --unset https.proxy

# 清除本地代理
git config --unset http.proxy
git config --unset https.proxy

# 验证已清除
git config --global --get http.proxy  # 应无输出

方案 2：为特定仓库禁用代理

# 设置空的代理（仅当前仓库）
git config --local http.proxy ""

# 或使用 --no-proxy 参数
GIT_NO_PROXY="git.haiguang.xyz" git push

方案 3：配置正确的代理

如果确实需要代理：

# 设置 HTTP 代理
git config --global http.proxy http://127.0.0.1:7890

# 设置 HTTPS 代理
git config --global https.proxy http://127.0.0.1:7890

# 设置不使用代理的域名
git config --global http.proxy 'http://127.0.0.1:7890'
git config --global https.proxy 'http://127.0.0.1:7890'

方案 4：使用环境变量

# Windows PowerShell
$env:HTTP_PROXY = ""
$env:HTTPS_PROXY = ""

# Linux/Mac
export HTTP_PROXY=""
export HTTPS_PROXY=""

# 推送
git push

验证连接

# 测试 Git 连接
git ls-remote https://git.haiguang.xyz/username/repo.git

# 测试网络连接（curl）
curl -v https://git.haiguang.xyz

---

问题 3：仓库路径错误

错误表现

git push -u origin main
remote: Not Found.
fatal: repository 'https://git.haiguang.xyz/giteah/llm_wiki.git/' not found

问题场景

尝试推送到不存在的仓库或错误的用户名/仓库名。

根本原因

1. 用户名错误：giteah vs giteahh（少了一个 h）
2. 仓库名错误：仓库名拼写错误
3. 仓库未创建：URL 中的仓库在 Gitea 上不存在
4. 权限不足：用户没有访问该仓库的权限

解决方案

步骤 1：验证远程 URL

# 查看当前远程配置
git remote -v

# 输出示例
# origin  https://git.haiguang.xyz/giteah/llm_wiki.git (fetch)
# origin  https://git.haiguang.xyz/giteah/llm_wiki.git (push)

步骤 2：检查 Gitea 仓库

1. 登录 Gitea：https://git.haiguang.xyz
2. 查看个人主页确认仓库名
3. 确认用户名（通常与 Gitea 登录账号一致）

步骤 3：修正 URL

# 方式 1：更新远程 URL
git remote set-url origin https://git.haiguang.xyz/正确的用户名/仓库名.git

# 方式 2：删除后重新添加
git remote remove origin
git remote add origin https://git.haiguang.xyz/正确的用户名/仓库名.git

# 验证
git remote -v

步骤 4：创建仓库（如果不存在）

在 Gitea 网页界面：

1. 点击右上角 "+" → "New Repository"
2. 填写仓库名（如 llm_wiki）
3. 选择可见性（公开/私有）
4. 不要勾选 "Initialize with README"
5. 点击创建

常见错误对比

错误 URL	正确 URL	差异
giteah/llm_wiki	giteahh/llm_wiki	用户名少一个 h
llm-wiki	llm_wiki	连字符 vs 下划线
Llm_Wiki	llm_wiki	大小写错误

---

问题 4：分支名称不匹配

错误表现

git push -u origin main
error: src refspec main does not match any
error: failed to push some refs to 'https://git.haiguang.xyz/.../llm_wiki.git'

问题场景

尝试推送到 main 分支，但本地只有 master 分支（或反之）。

根本原因

1. 初始化差异：旧版 Git 使用 master，新版使用 main
2. 远程仓库设置：Gitea 仓库的默认分支可能是 main
3. 本地分支未创建：本地没有指定名称的分支

解决方案

方案 1：推送实际存在的分支

# 查看本地分支
git branch

# 输出：* master（注意星号表示当前分支）

# 推送 master 分支
git push -u origin master

方案 2：重命名分支为 main

# 重命名当前分支
git branch -m master main

# 设置上游分支
git push -u origin main

# 验证
git branch -a

方案 3：切换到 main 分支（如果已存在）

# 切换分支
git checkout main

# 如果分支不存在，创建并切换
git checkout -b main

# 推送
git push -u origin main

方案 4：设置默认推送分支

# 设置默认上游分支
git branch --set-upstream-to=origin/master master

# 或使用 push.default 配置
git config push.default current

验证分支

# 查看所有分支（本地和远程）
git branch -a

# 查看远程分支
git branch -r

# 查看分支跟踪关系
git branch -vv

---

问题 5：HTTP 413 错误

错误表现

git push -u origin master
Enumerating objects: 685, done.
Counting objects: 100% (685/685), done.
Compressing objects: 100% (624/624), done.
Writing objects: 100% (685/685), 140.75 MiB | 809.00 KiB/s, done.
error: RPC failed; HTTP 413 curl 22 The requested URL returned error: 413
send-pack: unexpected disconnect while reading sideband packet
fatal: the remote end hung up unexpectedly

问题场景

首次推送大量文件（Obsidian vault 约 140MB）到 Gitea 服务器。

根本原因

1. Nginx 限制：client_max_body_size 默认值较小（如 1MB）
2. Gitea 限制：MAX_FILE_SIZE 配置限制
3. 代理限制：代理服务器对上传大小有限制

解决方案

方案 1：增加本地缓冲区（客户端）

# 增加本地 HTTP 缓冲区大小到 500MB
git config http.postBuffer 524288000

# 重试推送
git push -u origin master

注意：这只是临时缓解，如果服务器端限制更低，仍会失败。

方案 2：分批推送

# 先推送少量文件测试
git add README.md
git commit -m "Test commit"
git push

# 成功后再推送全部
git add .
git commit -m "Add all files"
git push

方案 3：使用 Git LFS（长期方案）

步骤 1：安装 Git LFS

# Windows（使用 Git Bash）
git lfs install

# Mac
brew install git-lfs
git lfs install

# Linux
sudo apt-get install git-lfs
git lfs install

步骤 2：追踪大文件

# 追踪特定扩展名
git lfs track "*.pdf"
git lfs track "*.psd"
git lfs track "*.mp4"

# 或追踪大于 10MB 的文件
git lfs track "*.png" --include="*.png" --attribute-size=10M

步骤 3：提交 .gitattributes

git add .gitattributes
git commit -m "Add Git LFS tracking"

步骤 4：推送

# 大文件会通过 LFS 上传
git push

方案 4：服务端配置（需要管理员权限）

Gitea 配置（app.ini）

[server]
HTTP_PORT = 3000
DOMAIN = git.haiguang.xyz
ROOT_URL = https://git.haiguang.xyz/

; 增加上传限制（单位：字节）
MAX_FILE_SIZE = 1073741824  # 1GB
MAX_CREATION_SIZE = 1073741824  # 1GB

[repository]
; 仓库相关限制
MAX_FILES = 1000000

Nginx 配置

server {
    listen 80;
    server_name git.haiguang.xyz;

    # 增加上传大小限制
    client_max_body_size 500M;
    client_body_timeout 300s;

    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

重启服务

# 重启 Nginx
sudo systemctl restart nginx

# 重启 Gitea
sudo systemctl restart gitea

方案 5：代理服务器配置

如果使用反向代理（如 Nginx、Apache），确保配置正确：

# Nginx 完整配置示例
upstream gitea {
    server 127.0.0.1:3000;
}

server {
    listen 443 ssl;
    server_name git.haiguang.xyz;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    # 关键配置
    client_max_body_size 500M;
    client_body_timeout 300s;

    location / {
        proxy_pass http://gitea;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # 增加超时
        proxy_read_timeout 300s;
        proxy_connect_timeout 300s;
        proxy_send_timeout 300s;
    }
}

验证配置

检查 Nginx 配置

# 测试配置文件
sudo nginx -t

# 查看当前限制
sudo nginx -T | grep client_max_body_size

检查 Gitea 配置

# 查看 Gitea 日志
sudo journalctl -u gitea -f

# 查看 Nginx 日志
sudo tail -f /var/log/nginx/error.log

最佳实践

实践	说明
首次推送小批量	先推送 README.md 测试连接
使用 Git LFS	大文件（>10MB）使用 LFS 管理
监控上传进度	使用 --progress 参数查看详情
服务端配置	预留足够的上传空间（建议 1GB+）

---

问题解决流程图

graph TD
    A[Git 推送失败] --> B{错误类型}
    B -->|config 损坏| C[删除并重建 .git/config]
    B -->|连接失败| D[检查/清除代理设置]
    B -->|Not Found| E[验证 URL 和仓库名]
    B -->|refspec 不匹配| F[检查分支名并推送]
    B -->|HTTP 413| G[增加缓冲或配置服务器]

    C --> H[重试推送]
    D --> H
    E --> H
    F --> H
    G --> H

    H --> I{成功?}
    I -->|是| J[✅ 完成]
    I -->|否| K[查看详细日志]

---

诊断命令

全面诊断

# 1. 检查 Git 版本
git --version

# 2. 检查仓库状态
git status

# 3. 检查分支
git branch -a

# 4. 检查远程配置
git remote -v

# 5. 检查配置
git config --list

# 6. 检查网络连接
curl -I https://git.haiguang.xyz

# 7. 测试 Git 连接
git ls-remote origin

日志查看

# Git 详细日志
GIT_CURL_VERBOSE=1 git push

# 或设置
git config --global http.sslVerify false
git config --global http.debug 1

---

经验总结

首次推送检查清单

• 仓库已在 Gitea 上创建
• 用户名和仓库名拼写正确
• Access Token 已配置
• .gitignore 文件已创建
• 代理设置已清除（如果不需要）
• 本地分支名称与远程匹配
• 服务器上传限制足够
• 大文件考虑使用 Git LFS

快速参考

问题	快速命令
config 损坏	rm .git/config && git config user.name "…"
代理问题	git config --unset http.proxy
仓库错误	git remote set-url origin https://正确URL
分支不匹配	git push -u origin $(git branch --show-current)
HTTP 413	git config http.postBuffer 524288000

来源

• Gitea 会话总结 - 2026-04-07 实际使用记录
• Gitea 官方文档：https://docs.gitea.com