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

giteahh/llm_wiki

Fork 0

Files

T

giteahh 407a9213bf feat(vault): Phase 3 tools + batch citation/relation enrichment

2026-07-01 15:20:40 +08:00

28 KiB

Raw Blame History

categories, tags, created, source, type, aliases, relations

问题概览


---------
1. `.git/config` 损坏
2. 代理连接失败
3. 仓库路径错误
4. 分支名不匹配
5. HTTP 413 错误

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

错误表现

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

问题场景

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

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

根本原因

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

解决方案

步骤 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 推送时无法通过代理连接。

根本原因

代理配置错误：代理地址或端口不正确
代理服务未运行：代理程序未启动
防火墙限制：防火墙阻止代理连接
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

问题场景

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

根本原因

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

解决方案

步骤 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 仓库

登录 Gitea：https://git.haiguang.xyz
查看个人主页确认仓库名
确认用户名（通常与 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 网页界面：

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

常见错误对比

错误 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 分支（或反之）。

根本原因

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

解决方案

方案 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 服务器。

根本原因

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

解决方案

方案 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

[raw:Gitea个人Git服务部署指南:2]# 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：备份并删除损坏文件

# 备份（可选）
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 推送时无法通过代理连接。

根本原因

代理配置错误：代理地址或端口不正确
代理服务未运行：代理程序未启动
防火墙限制：防火墙阻止代理连接
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

问题场景

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

根本原因

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

解决方案

步骤 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 仓库

登录 Gitea：https://git.haiguang.xyz
查看个人主页确认仓库名
确认用户名（通常与 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 网页界面：

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

常见错误对比

错误 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 分支（或反之）。

根本原因

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

解决方案

方案 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 服务器。

根本原因

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

解决方案

方案 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

28 KiB Raw Blame History Unescape Escape

问题概览

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

错误表现

问题场景

根本原因

解决方案

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

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

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

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

预防措施

问题 2：代理连接失败

错误表现

问题场景

根本原因

解决方案

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

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

方案 3：配置正确的代理

方案 4：使用环境变量

验证连接

问题 3：仓库路径错误

错误表现

问题场景

根本原因

解决方案

步骤 1：验证远程 URL

步骤 2：检查 Gitea 仓库

步骤 3：修正 URL

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

常见错误对比

问题 4：分支名称不匹配

错误表现

问题场景

根本原因

解决方案

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

方案 2：重命名分支为 main

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

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

验证分支

问题 5：HTTP 413 错误

错误表现

问题场景

根本原因

解决方案

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

方案 2：分批推送

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

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

方案 5：代理服务器配置

验证配置

检查 Nginx 配置

检查 Gitea 配置

最佳实践

问题解决流程图

诊断命令

全面诊断

日志查看

经验总结

首次推送检查清单

快速参考

来源

问题概览

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

错误表现

问题场景

根本原因

解决方案

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

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

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

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

预防措施

问题 2：代理连接失败

错误表现

问题场景

根本原因

解决方案

28 KiB

Raw Blame History

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

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