【计算机常识】--使用 Gitea 在本地/内网搭建 Git 私有服务器

在本地或内网使用 Gitea 搭建 Git 私有服务器，其安全性主要体现在以下几个方面：

综上，Gitea 在内网部署本身具备较高的基础安全性，但其整体安全水平高度依赖于部署者的配置规范、运维习惯和安全意识。合理规划和持续维护是保障私有 Git 服务长期安全运行的关键。

前提：你的某台电脑（可以是你的开发机或一台常开的服务器）已安装 Docker 和 Docker Compose。

目录

1.创建 Gitea 数据目录

2.创建 docker-compose.yml

3.设置目录权限（关键！）

4.启动 Gitea

5.初始化git服务器

1. 停止容器并清理

2. 手动创建配置文件

3. 修正权限并启动

4. 创建管理员账号

6.登录创建

1.创建 Gitea 数据目录

Gitea 的“数据目录”是你整个私有 Git 服务的所有核心资产所在地——包括代码仓库、用户数据、配置、附件、数据库等，必须妥善备份和保护。

Gitea 的数据目录中确实包含你托管的所有项目的完整 Git 仓库数据，但需要明确一点：

它存储的是 Git 仓库的“裸仓库”（bare repository），而不是你日常开发用的“工作副本”（working directory）。

1. 什么是“裸仓库”？

• 裸仓库没有工作区（即没有你平时看到的 .c、.py、.js 等源代码文件直接展开）。
• 它只包含 Git 内部的元数据和对象数据库（如 HEAD、config、objects/、refs/ 等目录）。
• 这是 Git 服务器（包括 GitHub、GitLab、Gitea）标准的存储方式，用于高效接收推送（push）和提供克隆（clone）。

路径示例： D:\\gitea-data\\gitea-repositories\\yourname\\myproject.git

这个 myproject.git 目录就是一个裸仓库。

找一个目录创建：

mkdir gitea

cd gitea

mkdir data

mkdir git-repos

2.创建 docker-compose.yml

在  gitea 下新建文件 docker-compose.yml，内容如下：

nano docker-compose.yml
version: '3.8'

services:
gitea:
image: gitea/gitea:latest
container_name: gitea
restart: always
environment:
– USER_UID=1000
– USER_GID=1000
# 如果你希望 Gitea 自动检测外部 URL，可加：
# – DOMAIN=localhost
# – ROOT_URL=http://localhost:3000/
volumes:
– /home/guoyuping/annotation_tool/gitea:/data
– /etc/localtime:/etc/localtime:ro
ports:
– "3000:3000" # Web 界面
– "2222:22" # SSH 端口（注意：不是默认 22，避免冲突）
networks:
– gitea-net

networks:
gitea-net:
external: false

• USER_UID=1000 和 USER_GID=1000：确保容器内 git 用户（UID=1000）能读写宿主机目录
• 端口 2222:22：将容器内的 SSH 服务（22）映射到宿主机的 2222 端口（避免与系统 SSH 冲突）
• 数据持久化：所有仓库、配置、数据库（SQLite）都存于 /home/guoyuping/annotation_tool/gitea/

3.设置目录权限（关键！）

Gitea 容器默认以 UID=1000 的 git 用户运行，必须确保该用户对数据目录有读写权限：

sudo chown -R 1000:1000 /home/guoyuping/annotation_tool/gitea

💡 验证：

ls -ld /home/guoyuping/annotation_tool/gitea
# 应显示：drwxr-xr-x … 1000 1000 …

4.启动 Gitea

# 在 gitea-deploy/ 目录下执行
docker-compose up -d

首次启动会自动拉取镜像并初始化。

5.初始化git服务器

打开：http://<你的服务器IP>:3000

✅ 安装完成后，自动跳转到登录页

失败了：

查看日志：

docker compose logs -f

Bug: gitea  | /usr/local/go/src/runtime/asm_amd64.s:1650 (0x475b60) gitea  | 2026/05/13 15:11:49 …s/install/install.go:226:checkDatabase() [I] Gitea will be installed in a database with: hasPostInstallationUser=false, dbMigrationVersion=280 gitea  | 2026/05/13 15:11:57 …/context_response.go:86:HTML() [E] Render failed: failed to render template: install, error: write tcp 172.29.0.2:3000->10.24.37.133:59127: write: broken pipe gitea  | 2026/05/13 15:11:57 …/context_response.go:88:HTML() [E] plainTextInternal (status=500): write bytes failed: write tcp 172.29.0.2:3000->10.24.37.133:59127: write: broken pipe gitea  | 2026/05/13 15:11:57 …rs/common/errpage.go:26:RenderPanicErrorPage() [E] PANIC: interface conversion: context.Context is nil, not *db.Context  

核心错误信息是：PANIC: interface conversion: context.Context is nil, not *db.Context。这通常意味着在安装引导界面提交表单时，Gitea 在尝试初始化数据库连接或渲染安装结果页面时丢失了上下文，导致程序崩溃。

造成 write: broken pipe 和 PANIC 的常见原因及解决方法如下：

1. 权限冲突（最可能的原因）

由于你手动指定了 /home/guoyuping/annotation_tool/gitea/ 目录，Docker 容器内的 git 用户（UID 1000）可能没有权限读写宿主机的这个文件夹。

解决方法： 在宿主机上执行以下命令，确保目录所有权属于容器内的用户：

当网页表单提交后，由于某些环境下的网络抖动导致 broken pipe，程序在尝试渲染错误页面时丢失了数据库上下文。

我们可以通过“跳过网页安装界面，直接使用配置文件启动”的方法来绕过这个报错。

请按照以下步骤操作：

1. 停止容器并清理

为了确保没有损坏的数据库残留，我们先彻底清空：

docker compose down
sudo rm -rf /home/guoyuping/annotation_tool/gitea/data/*

2. 手动创建配置文件

Gitea 的所有网页设置最终都会写进 app.ini。我们直接手动创建它，这样 Gitea 启动时就会发现“已经安装过了”，从而直接进入登录页面。

# 创建配置目录
mkdir -p /home/guoyuping/annotation_tool/gitea/data/gitea/conf/

# 创建并编辑 app.ini
nano /home/guoyuping/annotation_tool/gitea/data/gitea/conf/app.ini

将以下内容粘贴进去（注意修改 IP 为你的服务器实际 IP）：

Ini, TOML

APP_NAME = Gitea: Git with a cup of tea
RUN_MODE = prod
RUN_USER = git

[database]
DB_TYPE = sqlite3
PATH = /data/gitea/gitea.db
LOG_SQL = false

[repository]
ROOT = /data/git/repositories

[server]
SSH_DOMAIN = 10.24.37.133
HTTP_PORT = 3000
ROOT_URL = http://10.24.37.133:3000/
DISABLE_SSH = false
SSH_PORT = 2222
LFS_START_SERVER = true

[security]
INSTALL_LOCK = true
SECRET_KEY = $(head -c 32 /dev/urandom | base64)

[service]
DISABLE_REGISTRATION = false

3. 修正权限并启动

# 确保所有新建的配置文件夹权限属于 1009
sudo chown -R 1009:1009 /home/guoyuping/annotation_tool/gitea/data

# 启动容器
docker compose up -d

4. 创建管理员账号

由于我们跳过了网页安装，现在需要通过命令行手动创建一个管理员：

docker exec -it -u 1009 gitea gitea admin user create –username admin –password 你的

6.登录创建

使用刚才的用户密码登录进来

创建一个项目：

在pycharm中

第一次项目上传管理：

# 1. 初始化 Git
git init

# 2. 将所有文件添加到暂存区
git add .

# 3. 提交到本地仓库
git commit -m "首次上传代码"

# 4. 关联远程 Gitea 仓库 (使用 HTTP 地址)
git remote add origin http://10.24.37.133:3000/你的用户名/仓库名.git

# 5. 推送代码到 Gitea
# 此时会弹窗提示输入 Gitea 的用户名和密码
git push -u origin main

别的用户：

git clone http://10.24.37.133:3000/guoyuping/my-project.git #第一次拉取

#同步分支
git pull origin main

# 1. 暂存修改
git add .

# 2. 提交到本地
git commit -m "修正了某个功能"

# 3. 推送到服务器
git push origin main