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

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

网络隔离：部署在内网环境中，默认不对外暴露服务，有效防止来自公网的未授权访问、扫描和攻击，大幅降低外部威胁面。
数据自主可控 ：所有代码、用户信息、操作日志等敏感数据完全保留在组织内部，避免了将核心资产托管于第三方平台**（如 GitHub、GitLab.com）可能带来的合规性风险或数据泄露隐患。**
细粒度权限管理：Gitea 提供完善的用户/组织/仓库级权限控制机制（如只读、写入、管理员角色），支持团队协作中的最小权限原则，防止越权操作。
开源透明与社区维护：Gitea 采用 MIT 开源协议，代码公开可审计，安全漏洞通常能被社区快速发现和修复；同时保持轻量、低依赖，减少了攻击面。

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

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

[1.创建 Gitea 数据目录](#1.创建 Gitea 数据目录)

[2.创建 docker-compose.yml](#2.创建 docker-compose.yml)

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

[4.启动 Gitea](#4.启动 Gitea)

5.初始化git服务器

[1. 停止容器并清理](#1. 停止容器并清理)

[2. 手动创建配置文件](#2. 手动创建配置文件)

[3. 修正权限并启动](#3. 修正权限并启动)

[4. 创建管理员账号](#4. 创建管理员账号)

6.登录创建

1.创建 Gitea 数据目录

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

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

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

什么是"裸仓库"？

裸仓库没有工作区（即没有你平时看到的 .c、.py、.js 等源代码文件直接展开）。

它只包含 Git 内部的元数据和对象数据库（如 HEAD、config、objects/、refs/ 等目录）。

这是 Git 服务器（包括 GitHub、GitLab、Gitea）标准的存储方式，用于高效接收推送（push）和提供克隆（clone）。

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

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

找一个目录创建：

bash 复制代码

mkdir gitea

cd gitea

mkdir data


mkdir git-repos

2.创建 `docker-compose.yml`

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

bash 复制代码

nano docker-compose.yml

bash 复制代码

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 用户运行，必须确保该用户对数据目录有读写权限：

bash 复制代码

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

💡 验证：

bash 复制代码

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

4.启动 Gitea

bash 复制代码

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

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

5.初始化git服务器

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

打开 http://服务器IP:3000

数据库选择 SQLite3（默认，无需额外配置）

域名填写：localhost 或你的服务器 IP

SSH 服务器域名：localhost（或 IP）

SSH 端口：2222 （必须与 docker-compose.yml 中映射端口一致！）

创建管理员账号（如 guoyuping）

点击 立即安装

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

失败了：

查看日志：

bash 复制代码

 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中

第一次项目上传管理：

bash 复制代码

# 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

别的用户：

bash 复制代码

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