llm_wiki/wiki/Gitea.md

categories, tags, created, source, type, aliases

categories	tags	created	source	type	aliases
LLM Wiki	wiki tool git version-control	2026-04-07	Gitea个人Git服务部署指南	tool	Gitea 使用指南 Gitea 配置

Gitea

一句话描述：轻量级、自托管的 Git 托管服务

基本信息

属性	值
官网	https://gitea.io
类型	Git 托管服务
开源	✅ 是

在 LLM Wiki 中的角色

用于托管 Obsidian vault 的 Git 版本控制，提供：

• 远程仓库备份
• 版本历史追踪
• 团队协作能力
• API 访问（通过 Access Token）

基础配置流程

1. 初始化本地仓库

cd /path/to/your/repo
git init

2. 创建 .gitignore

Obsidian vault 的推荐 .gitignore：

# Obsidian
.obsidian/workspace.json
.obsidian/workspace-mobile.json

# 导出文件
*.pdf
*.html
*.pptx

# 临时文件
.DS_Store
Thumbs.db

3. 配置远程仓库

git remote add origin https://git.haiguang.xyz/username/repo.git

4. Access Token 认证

创建 Access Token（推荐方式）：

1. 登录 Gitea
2. 进入设置 → Applications → Access Tokens
3. 创建新 Token，勾选需要的权限（如 read/write）
4. 使用 Token 推送：

# 方式 1：在 URL 中包含 Token
git remote set-url origin https://<token>@git.haiguang.xyz/username/repo.git

# 方式 2：使用 Git Credential Manager
git push  # 会提示输入用户名和 Token

重要：

• ✅ 推荐：使用 Token 而非密码
• ✅ Token 权限应最小化原则
• ❌ 不要将 Token 硬编码到脚本中

首次推送

# 创建初始分支（如果需要）
git checkout -b main

# 添加所有文件
git add .

# 创建初始提交
git commit -m "Initial commit"

# 推送到远程
git push -u origin main

常见问题排查

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

错误：

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

原因：写入操作失败或手动编辑错误

解决方案：

# 删除损坏的配置
rm .git/config

# 重新配置
git config user.name "Your Name"
git config user.email "your@email.com"
git remote add origin https://git.haiguang.xyz/username/repo.git

问题 2：代理/网络连接失败

错误：

Failed to connect to git.haiguang.xyz port 443 via 127.0.0.1:7890

原因：系统配置了 HTTP 代理

解决方案：

# 清除代理设置
git config --global --unset http.proxy
git config --global --unset https.proxy

# 或为特定仓库设置
git config --unset http.proxy
git config --unset https.proxy

问题 3：仓库路径错误

错误：

remote: Not Found
fatal: repository 'https://git.haiguang.xyz/giteah/llm_wiki.git/' not found

原因：用户名或仓库名不正确

解决方案：

1. 确认 Gitea 仓库已创建
2. 检查 URL 格式：https://git.haiguang.xyz/用户名/仓库名.git
3. 常见错误：
   • 用户名错误（giteah vs giteahh）
   • 仓库名拼写错误
   • 仓库未创建（需要先在 Gitea 上创建）

问题 4：分支名称不匹配

错误：

error: src refspec main does not match any

原因：本地分支名与远程分支名不一致

解决方案：

# 查看本地分支
git branch

# 情况 1：推送 master 分支
git push -u origin master

# 情况 2：重命名为 main
git branch -m master main
git push -u origin main

问题 5：HTTP 413 错误

错误：

error: RPC failed; HTTP 413 curl 22 The requested URL returned error: 413

原因：Gitea 服务器限制上传大小（默认较小）

场景：

• 首次推送大量文件（如 685 个对象，约 140MB）
• 单个文件过大

解决方案：

客户端方案（临时缓解）：

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

# 重试推送
git push -u origin master

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

1. 编辑 Gitea 配置文件（app.ini）：

[server]
HTTP_PORT = 3000
; 增加上传限制（单位：字节）
MAX_FILE_SIZE = 1048576000  # 1GB

[repository]
; 增加 Git 上传大小限制
MAX_CREATION_SIZE = 1048576000

2. 或修改 Nginx 配置：

client_max_body_size 500M;

3. 重启 Gitea 服务

长期方案：

• 大文件应使用 Git LFS（Large File Storage）
• 分批推送（先推送少量文件测试）

最佳实践

安全性

实践	说明
使用 Access Token	避免密码泄露，权限可控
最小权限原则	Token 只授予必要的权限
定期轮换 Token	每隔几个月更新一次
不硬编码 Token	使用环境变量或 Git Credential Manager

工作流

# 日常开发
git add .
git commit -m "Add new notes"
git push

# 拉取更新
git pull

# 查看状态
git status
git log --oneline -10

团队协作

# 创建分支
git checkout -b feature/new-topic

# 提交并推送
git add .
git commit -m "Add new topic"
git push -u origin feature/new-topic

# 合并到主分支
git checkout main
git merge feature/new-topic
git push

与 Obsidian 集成

.gitignore 优化

# Obsidian 配置（个人化）
.obsidian/workspace.json
.obsidian/workspace-mobile.json
.obsidian/graph.json

# 临时文件
.obsidian/trash/
.obsidian/*.swp

# 导出产物
*.pdf
*.html
*.pptx
*.png
*.jpg

自动化建议

• 使用 Obsidian Git 插件自动提交
• 配置 Git Hook（如 pre-commit 检查）
• 使用 CI/CD（如 GitHub Actions）自动备份到其他位置

来源

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