CentOS 7 Gitea 安装文档（Docker Compose 方式）

适用于：仅 N1 服务器，轻量级 Git 代码仓库

前置条件

• 已完成 Docker 安装
• 已完成 MySQL 安装

1. 创建目录结构

sudo mkdir -p /opt/gitea/{data,config}
cd /opt/gitea

2. 获取宿主机 IP

# 获取 IP 用于数据库连接配置
HOST_IP=$(hostname -I | awk '{print $1}')
echo "宿主机 IP: $HOST_IP"

3. 创建 docker-compose.yml

# 请将 YOUR_HOST_IP 替换为实际 IP
cat > /opt/gitea/docker-compose.yml <<'EOF'
version: "3.8"

services:
  gitea:
    image: gitea/gitea:latest
    container_name: gitea
    restart: unless-stopped
    ports:
      - "3000:3000"
      - "2222:22"
    environment:
      - USER_UID=1000
      - USER_GID=1000
      - TZ=Asia/Shanghai
      # 数据库配置 - 请修改 YOUR_HOST_IP 为实际 IP
      - GITEA__database__DB_TYPE=mysql
      - GITEA__database__HOST=YOUR_HOST_IP:3306
      - GITEA__database__NAME=gitea
      - GITEA__database__USER=gitea
      - GITEA__database__PASSWD=YourGiteaPassword123!
      # 服务配置 - 请修改 YOUR_HOST_IP 为实际 IP
      - GITEA__server__ROOT_URL=http://YOUR_HOST_IP:3000/
      - GITEA__server__SSH_DOMAIN=YOUR_HOST_IP
      - GITEA__server__SSH_PORT=2222
      # 安全配置（初始化完成后改为 true）
      - GITEA__service__DISABLE_REGISTRATION=false
    volumes:
      - /opt/gitea/data:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro

EOF

重要：修改配置中的 YOUR_HOST_IP 为实际 IP 地址

# 自动替换 IP（可选）
HOST_IP=$(hostname -I | awk '{print $1}')
sed -i "s/YOUR_HOST_IP/$HOST_IP/g" /opt/gitea/docker-compose.yml

4. 启动服务

cd /opt/gitea
docker compose up -d

# 查看日志
docker compose logs -f

5. 开放防火墙端口

sudo firewall-cmd --permanent --add-port=3000/tcp
sudo firewall-cmd --permanent --add-port=2222/tcp
sudo firewall-cmd --reload

6. Web 界面初始化

6.1 访问安装向导

• 浏览器访问：http://YOUR_HOST_IP:3000
• 如果环境变量配置正确，数据库信息会自动填充
  

配置说明与推荐设置

1️⃣ Database Settings（数据库设置）

配置项	说明	推荐设置
Database Type	数据库类型	✅ 保持 MySQL（已自动填充）
Host	数据库地址和端口	✅ 保持不变（如 192.168.110.217:3306）
Username	数据库用户名	✅ 保持 gitea（已自动填充）
Password	数据库密码	✅ 保持不变（已自动填充）
Database Name	数据库名称	✅ 保持 gitea（已自动填充）

说明：这些值已通过 docker-compose.yml 的环境变量自动配置，无需修改。

2️⃣ General Settings（常规设置）

配置项	说明	推荐设置
Site Title	网站标题	📝 建议修改为：公司代码仓库 或 开发团队 Git
Repository Root Path	仓库存储路径	✅ 保持默认 /data/git/repositories
Git LFS Root Path	Git LFS 存储路径	✅ 保持默认 /data/git/lfs
Run As Username	运行用户	✅ 保持默认 git
Server Domain	服务器域名/IP	✅ 保持不变（如 192.168.110.217）
SSH Server Port	SSH 端口	✅ 保持 2222（已配置）
Gitea HTTP Listen Port	HTTP 监听端口	✅ 保持默认 3000
Gitea Base URL	基础访问地址	✅ 保持不变（如 http://192.168.110.217:3000/）
Log Path	日志路径	✅ 保持默认 /data/gitea/log
Enable Update Checker	启用更新检查器，定期连接 gitea.io 检查新版本	❌ 不勾选（内网环境避免外网连接，Docker 更新通过拉取新镜像完成）

3️⃣ Optional Settings（可选设置）

展开 Email Settings（邮件设置）：

配置项	说明	推荐设置
SMTP Host	SMTP 邮件服务器地址	📝 如有企业邮箱填写，如 smtp.example.com，否则留空
SMTP Port	SMTP 端口	📝 通常为 465（SSL）或 587（TLS），留空则跳过
Send Email As	发件人邮箱地址	📝 如 gitea@example.com 或 "Gitea" <gitea@example.com>
SMTP Username	SMTP 用户名	📝 通常为邮箱地址
SMTP Password	SMTP 密码	📝 邮箱密码或授权码
Require Email Confirmation to Register	注册时需要邮箱验证	❌ 不勾选（除非配置了邮件服务）
Enable Email Notifications	启用邮件通知	❌ 不勾选（除非配置了邮件服务）

说明：邮件设置为可选，如果暂时不需要邮件功能，可以全部留空，后续在配置文件中添加。

展开 Server and Third-Party Service Settings（服务器和第三方服务设置）：

配置项	说明	推荐设置
Enable Local Mode	启用本地模式，禁用所有外部资源	✅ 勾选（内网环境推荐）
Disable Gravatar	禁用 Gravatar 头像服务	✅ 勾选（避免访问外网，提升速度）
Enable Federated Avatars	启用联合头像查找	❌ 不勾选（内网环境无需）
Enable OpenID Sign-In	启用 OpenID 登录	❌ 不勾选（除非需要第三方登录）
Disable Self-Registration	禁用自助注册	❌ 不勾选（初始化时保持开放，后续可关闭）
Allow Registration Only Through External Services	仅允许通过外部服务注册	❌ 不勾选
Enable OpenID Self-Registration	启用 OpenID 自助注册	❌ 不勾选
Enable Registration CAPTCHA	启用注册验证码	❌ 不勾选（内网环境无需）
Require Sign-In to View Pages	查看页面需要登录	✅ 可选勾选（私有部署建议勾选，增强安全性）
Hide Email Addresses by Default	默认隐藏邮箱地址	✅ 勾选（保护用户隐私）
Allow Creation of Organizations by Default	默认允许创建组织	✅ 保持勾选（方便团队管理）
Enable Time Tracking by Default	默认启用时间追踪	✅ 保持勾选（可追踪工作时间）
Hidden Email Domain	隐藏邮箱域名	✅ 保持默认 noreply.localhost
Password Hash Algorithm	密码哈希算法	✅ 保持默认 pbkdf2（安全且兼容性好）

展开 Administrator Account Settings（重要）：

配置项	说明	推荐设置
Administrator Username	管理员用户名	📝 填写：admin 或 gitadmin
Email Address	管理员邮箱	📝 填写：admin@example.com
Password	管理员密码	📝 设置强密码（至少8位，包含大小写字母、数字）
Confirm Password	确认密码	📝 重复输入密码

⚠️ 重要提示：

• 管理员账号必须在此创建，这是唯一一次通过 Web 界面创建的机会
• 如果跳过，后续只能通过命令行创建管理员
• 密码建议使用强密码，包含大小写字母、数字和特殊字符

4️⃣ 完成配置

检查所有配置无误后，点击页面底部的 “Install Gitea” 按钮完成安装。

6.2 安装完成后的首次登录

安装完成后，页面会自动跳转到登录界面。使用刚才创建的管理员账号登录。

6.3 设置中文界面

• 登录后点击右上角头像 → 设置
• 在「外观」中选择「简体中文」
  
  
  

7. 用户管理

Gitea 默认只支持用户自行注册，管理后台没有直接新增用户的菜单。如需后台添加用户，使用命令行：

# 创建普通用户
docker exec -it --user git gitea gitea admin user create \
  --username newuser \
  --password YourPassword123 \
  --email user@example.com

# 创建管理员用户
docker exec -it --user git gitea gitea admin user create \
  --username newadmin \
  --password YourPassword123 \
  --email admin@example.com \
  --admin

8. 如何关闭公开注册

初始化完成后，若要关闭公开注册：

cd /opt/gitea

# 修改配置
sed -i 's/DISABLE_REGISTRATION=false/DISABLE_REGISTRATION=true/g' docker-compose.yml

# 重启服务
docker compose down
docker compose up -d

9. 生成 Jenkins 访问令牌

1. 登录 Gitea
2. 点击右上角头像 → 设置 → 应用
3. 在「管理访问令牌」部分，输入令牌名称（如 jenkins）
4. 选择权限范围（建议选择 repo）
5. 点击「生成令牌」
6. 立即复制保存令牌（只显示一次）
   
   

10. 常用管理命令

cd /opt/gitea

# 启动
docker compose up -d

# 停止
docker compose down

# 重启
docker compose restart

# 查看日志
docker compose logs -f gitea

# 进入容器
docker exec -it gitea bash

# 备份数据
sudo tar -czvf gitea_backup_$(date +%Y%m%d).tar.gz /opt/gitea/data

11. 组织、团队、仓库概念说明

11.1 三者关系

组织（Organization）
├── 团队A（Team）──── 管理 ────→ 仓库1、仓库2
├── 团队B（Team）──── 管理 ────→ 仓库2、仓库3
└── 仓库（Repository）
    ├── 仓库1
    ├── 仓库2
    └── 仓库3

概念	说明
组织	容器，用于承载团队和仓库，类似公司的"项目组"或"部门"
团队	人员分组，属于某个组织，可分配不同仓库的访问权限
仓库	代码仓库，属于某个组织，可被多个团队共同管理

核心理解：组织是中间层，是团队和仓库的容器。团队不能脱离组织存在，仓库也必须归属于某个组织（或个人）。

11.2 示例一：跨部门临时项目

场景：公司临时接到项目A，需要从技术1部和技术2部各抽调3人组成临时团队。

操作步骤：

1. 创建组织
   • 点击右上角「+」→「新建组织」
   • 组织名称：tempOrg（临时组织）
   • 可见性：私有

2. 创建仓库

   • 进入组织 tempOrg

   • 点击「新建仓库」

   • 仓库名称：proA（项目A）

   • 可见性：私有

     
     

3. 创建团队

   • 点击进入某个组织 → 「团队」标签
   • 点击「新建团队」
   • 团队名称：输入一个团队名称
   • 权限：代码 → 写入（可推送代码）

4. 添加成员到团队
   • 进入某个组织，再点击某个团队名称进入团队
   • 点击「成员」→「添加团队成员」
   • 添加从两个部门抽调的6人

5. 分配仓库给团队
   • 进入团队 teamA → 「仓库」标签
   • 点击「添加仓库」
   • 选择 proA

结果：6名成员通过团队获得了项目A仓库的写入权限。

11.3 示例二：多团队协作同一仓库

场景：一个产品仓库需要开发组有写入权限，测试组只有读取权限。

操作步骤：

1. 在组织下创建仓库 product-app

2. 创建两个团队：

   • dev-team（开发组）- 权限：写入
   • test-team（测试组）- 权限：读取

3. 将同一个仓库分配给两个团队（权限不同）

11.4 权限级别说明

权限	说明
读取	只能查看代码、克隆仓库
写入	可以推送代码、创建分支
管理员	完全控制，可修改仓库设置

11.5 常用操作路径

操作	路径
创建组织	右上角「+」→「新建组织」
创建团队	组织页面 →「团队」→「新建团队」
添加成员	团队页面 →「成员」→「添加团队成员」
分配仓库	团队页面 →「仓库」→「添加仓库」
转移仓库	仓库设置 →「危险操作区」→「转移仓库所有权」

11.6 仓库复制与迁移

方式一：派生（Fork）

适用场景：复制 Gitea 内部已有的仓库到自己名下或其他组织。

操作步骤：

1. 进入要复制的仓库页面，点击右上角「派生」按钮

   

2. 选择目标拥有者（个人用户或组织），点击「派生仓库」

   

特点：

• 派生后的仓库与原仓库保持关联
• 可以向原仓库发起合并请求（Pull Request）
• 适合协作开发场景

方式二：迁移外部仓库

适用场景：从 GitHub、GitLab 等外部平台导入仓库到 Gitea。

操作步骤：

1. 进入目标组织页面，点击「迁移外部仓库」

   

2. 选择迁移来源平台（GitHub、GitLab、Gitea 等）

   

3. 填写迁移信息：

   • 仓库 URL：外部仓库的克隆地址
   • 访问令牌：私有仓库需要提供（可选）
   • 拥有者：选择目标组织或用户
   • 仓库名称：在 Gitea 中的名称
   • 勾选需要迁移的项目（Wiki、Issue、标签等）

   

4. 点击「迁移仓库」完成导入

特点：

• 完全独立的副本，与原仓库无关联
• 可迁移 Issue、Wiki、标签等附属内容
• 适合从其他平台迁移项目

迁移内网仓库报错解决

如果从内网地址（如 192.168.x.x）迁移仓库时出现以下错误：

您不能从不允许的主机导入，请询问管理员以检查 ALLOWED_DOMAINS/ALLOW_LOCALNETWORKS/BLOCKED_DOMAINS 设置。

原因：Gitea 默认不允许从本地网络地址迁移仓库，这是一个安全限制。

解决方法：

1. 编辑 Gitea 配置文件，添加迁移配置：

cat >> /opt/gitea/data/gitea/conf/app.ini << 'EOF'

[migrations]
ALLOW_LOCALNETWORKS = true
ALLOWED_DOMAINS = *
EOF

2. 重启 Gitea 容器使配置生效：

cd /opt/gitea
docker compose restart

配置说明：

配置项	说明
ALLOW_LOCALNETWORKS	设为 true 允许从本地网络（192.168.x.x、10.x.x.x、172.16.x.x 等）迁移
ALLOWED_DOMAINS	设为 * 允许所有域名，也可指定具体域名如 github.com,gitlab.com

12. 常见问题

12.1 数据库连接失败

• 确认 MySQL 容器正在运行
• 确认数据库密码正确
• 确认 HOST_IP 配置正确

12.2 SSH 克隆失败

• 使用正确格式：ssh://git@YOUR_HOST_IP:2222/owner/repo.git
• 确认 2222 端口已开放

12.3 页面跳转异常

• 检查 ROOT_URL 配置是否与访问地址一致