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

---
categories:
  - "[[LLM Wiki]]"
tags:
  - wiki
  - troubleshooting
  - git
  - gitea
created: 2026-04-07
source: "[[Gitea个人Git服务部署指南]]"
type: concept
aliases:
  - 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` 文件损坏

### 错误表现

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

### 问题场景

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

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

### 根本原因

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

### 解决方案

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

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

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

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

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

# 验证配置
cat .git/config
```

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

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

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

# 验证
git remote -v
```

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

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

```ini
[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/*
```

### 预防措施

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

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

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

---

## 问题 2：代理连接失败

### 错误表现

```bash
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：清除代理设置（推荐）

```bash
# 清除全局代理
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：为特定仓库禁用代理

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

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

#### 方案 3：配置正确的代理

如果确实需要代理：

```bash
# 设置 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：使用环境变量

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

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

# 推送
git push
```

### 验证连接

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

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

---

## 问题 3：仓库路径错误

### 错误表现

```bash
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

```bash
# 查看当前远程配置
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

```bash
# 方式 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：分支名称不匹配

### 错误表现

```bash
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：推送实际存在的分支

```bash
# 查看本地分支
git branch

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

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

#### 方案 2：重命名分支为 main

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

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

# 验证
git branch -a
```

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

```bash
# 切换分支
git checkout main

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

# 推送
git push -u origin main
```

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

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

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

### 验证分支

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

# 查看远程分支
git branch -r

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

---

## 问题 5：HTTP 413 错误

### 错误表现

```bash
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：增加本地缓冲区（客户端）

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

# 重试推送
git push -u origin master
```

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

#### 方案 2：分批推送

```bash
# 先推送少量文件测试
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**

```bash
# 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：追踪大文件**

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

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

**步骤 3：提交 .gitattributes**

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

**步骤 4：推送**

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

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

**Gitea 配置（app.ini）**

```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 配置**

```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;
    }
}
```

**重启服务**

```bash
# 重启 Nginx
sudo systemctl restart nginx

# 重启 Gitea
sudo systemctl restart gitea
```

#### 方案 5：代理服务器配置

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

```nginx
# 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 配置

```bash
# 测试配置文件
sudo nginx -t

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

#### 检查 Gitea 配置

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

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

### 最佳实践

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

---

## 问题解决流程图

```mermaid
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[查看详细日志]
```

---

## 诊断命令

### 全面诊断

```bash
# 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
```

### 日志查看

```bash
# 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>