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

2026-07-01 15:20:40 +08:00
parent 8273017082
commit 407a9213bf
548 changed files with 53410 additions and 2113 deletions
@@ -1,20 +1,698 @@
 ---
 categories:
-  - "[[LLM Wiki]]"
+  - '[[LLM Wiki]]'
 tags:
  - wiki
  - troubleshooting
  - git
  - gitea
 created: 2026-04-07
-source: "[[Gitea个人Git服务部署指南]]"
+source: '[[Gitea个人Git服务部署指南]]'
 type: concept
 aliases:
  - Gitea 问题排查
  - Git 推送失败
+relations:
+  - type: part_of
+    target: '[[Gitea-部署指南]]'
+    description: 同源：Gitea个人Git服务部署指南
+    confidence: 3
 ---

-# Gitea 故障排查
+[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` 文件损坏
+
+### 错误表现
+
+```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>
+
+[raw:Gitea个人Git服务部署指南:2]# Gitea 故障排查

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