---
categories:
  - '[[LLM Wiki]]'
tags:
  - wiki
  - tool
  - git
  - version-control
created: 2026-04-07
source: '[[Gitea个人Git服务部署指南]]'
type: tool
aliases:
  - Gitea 使用指南
  - Gitea 配置
relations:
  - type: part_of
    target: '[[Gitea-部署指南]]'
    description: 同源：Gitea个人Git服务部署指南
    confidence: 3
---

[raw:Gitea个人Git服务部署指南:2]# 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>

[raw:Gitea个人Git服务部署指南:2]# 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>