hehaiguang1123
a6f05ab2d5
- Phase 0: AGENTS.md cleanup (dedup quotes, renumber sections, merge qmd) - Phase 1: typed relations (manage-relations.py, graph-search.py, check-staleness.py, detect-conflicts.py) - Phase 2: frontmatter validator, weekly lint, knowledge promotion, git hooks - Fix .gitignore to track tools/ and .githooks/ - Fix git remote URL (remove plaintext token) - New wiki pages: 504 pages, 34 raw sources
323 lines
5.7 KiB
Markdown
323 lines
5.7 KiB
Markdown
---
|
||
categories:
|
||
- "[[LLM Wiki]]"
|
||
tags:
|
||
- wiki
|
||
- tool
|
||
- git
|
||
- version-control
|
||
created: 2026-04-07
|
||
source: "[[Gitea个人Git服务部署指南]]"
|
||
type: tool
|
||
aliases:
|
||
- Gitea 使用指南
|
||
- Gitea 配置
|
||
---
|
||
|
||
# Gitea
|
||
|
||
> **一句话描述**：轻量级、自托管的 Git 托管服务
|
||
|
||
## 基本信息
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 官网 | <https://gitea.io> |
|
||
| 类型 | Git 托管服务 |
|
||
| 开源 | ✅ 是 |
|
||
|
||
## 在 LLM Wiki 中的角色
|
||
|
||
用于托管 Obsidian vault 的 Git 版本控制，提供：
|
||
|
||
- 远程仓库备份
|
||
- 版本历史追踪
|
||
- 团队协作能力
|
||
- API 访问（通过 Access Token）
|
||
|
||
## 基础配置流程
|
||
|
||
### 1. 初始化本地仓库
|
||
|
||
```bash
|
||
cd /path/to/your/repo
|
||
git init
|
||
```
|
||
|
||
### 2. 创建 .gitignore
|
||
|
||
Obsidian vault 的推荐 `.gitignore`：
|
||
|
||
```gitignore
|
||
# Obsidian
|
||
.obsidian/workspace.json
|
||
.obsidian/workspace-mobile.json
|
||
|
||
# 导出文件
|
||
*.pdf
|
||
*.html
|
||
*.pptx
|
||
|
||
# 临时文件
|
||
.DS_Store
|
||
Thumbs.db
|
||
```
|
||
|
||
### 3. 配置远程仓库
|
||
|
||
```bash
|
||
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 推送：
|
||
|
||
```bash
|
||
# 方式 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 硬编码到脚本中
|
||
|
||
## 首次推送
|
||
|
||
```bash
|
||
# 创建初始分支（如果需要）
|
||
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
|
||
```
|
||
|
||
**原因**：写入操作失败或手动编辑错误
|
||
|
||
**解决方案**：
|
||
```bash
|
||
# 删除损坏的配置
|
||
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 代理
|
||
|
||
**解决方案**：
|
||
|
||
```bash
|
||
# 清除代理设置
|
||
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
|
||
```
|
||
|
||
**原因**：本地分支名与远程分支名不一致
|
||
|
||
**解决方案**：
|
||
|
||
```bash
|
||
# 查看本地分支
|
||
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）
|
||
- 单个文件过大
|
||
|
||
**解决方案**：
|
||
|
||
**客户端方案**（临时缓解）：
|
||
|
||
```bash
|
||
# 增加本地缓冲区大小
|
||
git config http.postBuffer 524288000 # 500MB
|
||
|
||
# 重试推送
|
||
git push -u origin master
|
||
```
|
||
|
||
**服务端方案**（需要管理员权限）：
|
||
|
||
1. 编辑 Gitea 配置文件（`app.ini`）：
|
||
|
||
```ini
|
||
[server]
|
||
HTTP_PORT = 3000
|
||
; 增加上传限制（单位：字节）
|
||
MAX_FILE_SIZE = 1048576000 # 1GB
|
||
|
||
[repository]
|
||
; 增加 Git 上传大小限制
|
||
MAX_CREATION_SIZE = 1048576000
|
||
```
|
||
|
||
2. 或修改 Nginx 配置：
|
||
|
||
```nginx
|
||
client_max_body_size 500M;
|
||
```
|
||
|
||
3. 重启 Gitea 服务
|
||
|
||
**长期方案**：
|
||
- 大文件应使用 Git LFS（Large File Storage）
|
||
- 分批推送（先推送少量文件测试）
|
||
|
||
## 最佳实践
|
||
|
||
### 安全性
|
||
|
||
| 实践 | 说明 |
|
||
|------|------|
|
||
| **使用 Access Token** | 避免密码泄露，权限可控 |
|
||
| **最小权限原则** | Token 只授予必要的权限 |
|
||
| **定期轮换 Token** | 每隔几个月更新一次 |
|
||
| **不硬编码 Token** | 使用环境变量或 Git Credential Manager |
|
||
|
||
### 工作流
|
||
|
||
```bash
|
||
# 日常开发
|
||
git add .
|
||
git commit -m "Add new notes"
|
||
git push
|
||
|
||
# 拉取更新
|
||
git pull
|
||
|
||
# 查看状态
|
||
git status
|
||
git log --oneline -10
|
||
```
|
||
|
||
### 团队协作
|
||
|
||
```bash
|
||
# 创建分支
|
||
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 优化
|
||
|
||
```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>
|