在企业内部研发环境中，我们经常需要一套：

• ✅ 私有化部署
• ✅ 轻量级
• ✅ 支持 Git 仓库 + Web 管理
• ✅ 支持 HTTP / SSH 推送
• ✅ 资源占用低

这时，Gitea 无疑是一个非常优秀的选择。
本文将基于一次完整的实战过程，详细讲解如何使用 Docker Compose + PostgreSQL 快速搭建一套稳定可用的 Gitea 私有代码仓库，并解决实际遇到的 SSH 端口冲突问题。

---

一、整体架构说明

本次部署采用如下架构：

组件	说明
Gitea	Git 代码托管服务
PostgreSQL	Gitea 元数据存储
Docker Compose	统一编排管理
数据目录	宿主机挂载，保证数据安全

访问方式：

• Web 管理端口：3000
• SSH 推送端口：本次关闭内置 SSH，避免 22 端口冲突

---

二、准备宿主机目录

在 Linux 服务器上创建统一的数据目录：

mkdir -p /data/docker/gitea/postgres
mkdir -p /data/docker/gitea/data
chown -R 1000:1000 /data/docker/gitea

说明：

• postgres：存放数据库数据
• data：存放 Gitea 所有业务数据（仓库、配置、附件等）
• 1000:1000 对应 Gitea 容器内的默认运行用户，避免权限问题

---

三、Docker Compose 编排文件

以下是完整可用的 docker-compose.yml：

version: "3.8"

services:
  db:
    image: postgres:16-alpine
    container_name: gitea-db
    restart: always
    environment:
      - POSTGRES_DB=gitea
      - POSTGRES_USER=gitea
      - POSTGRES_PASSWORD=gitea123    # 可自行修改为更复杂的密码
    volumes:
      - /data/docker/gitea/postgres:/var/lib/postgresql/data
    networks:
      - gitea

  gitea:
    image: gitea/gitea:latest
    container_name: gitea
    restart: always
    depends_on:
      - db
    ports:
      - "3000:3000"   # Web 访问端口
      - "222:22"      # (已关闭内置 SSH，仅保留映射)
    environment:
      - USER_UID=1000
      - USER_GID=1000

      # 数据库配置
      - GITEA__database__DB_TYPE=postgres
      - GITEA__database__HOST=db:5432
      - GITEA__database__NAME=gitea
      - GITEA__database__USER=gitea
      - GITEA__database__PASSWD=gitea123

      # 服务器访问配置
      - GITEA__server__DOMAIN=192.168.152.136
      - GITEA__server__ROOT_URL=http://192.168.152.136:3000/
      - GITEA__server__SSH_PORT=222

      # ✅ 关键点：关闭 Gitea 内置 SSH 服务，避免 22 端口冲突
      - GITEA__server__START_SSH_SERVER=false

    volumes:
      - /data/docker/gitea/data:/data
    networks:
      - gitea

networks:
  gitea:
    driver: bridge

⚠️ 注意：
192.168.152.136 请替换为你自己的服务器 IP 或域名。

---

四、启动服务

在 docker-compose.yml 所在目录执行：

docker-compose up -d

查看容器状态：

docker ps

日志查看：

docker logs -f gitea
docker logs -f gitea-db

---

五、防火墙与访问

如果服务器开启了防火墙，需要放行端口：

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

浏览器访问：

http://192.168.152.136:3000

进入 Gitea 初始化界面。

---

六、Gitea 初始化说明

由于我们已经使用环境变量配置了 PostgreSQL，因此初始化页面：

• 数据库类型：PostgreSQL（自动识别）
• 主机：db:5432
• 数据库名：gitea
• 用户名：gitea
• 密码：gitea123

只需确认以下两项即可：

• 站点标题：自定义
• Base URL：http://192.168.152.136:3000/

点击 “立即安装” 即可完成初始化。

---

七、管理员账号说明

✅ Gitea 没有默认账号密码
✅ 初始化完成后，第一个注册的用户自动成为管理员

如果忘记了管理员密码，可以通过以下方式重置：

docker exec -it gitea bash
gitea admin user list
gitea admin user change-password --username admin --password 123456

---

八、解决 SSH 端口冲突问题（实战踩坑）

在部署过程中，容器日志出现以下致命错误：

listen tcp :22: bind: address already in use
Failed to start SSH server

原因是：

• 服务器本身已有系统 SSH 服务占用了 22 端口
• Gitea 默认也尝试监听 22 端口，导致冲突
• Gitea 将该错误视为致命错误，容器直接退出

✅ 解决方案：

- GITEA__server__START_SSH_SERVER=false

即：关闭 Gitea 内置 SSH，只使用 HTTP Clone / Push

如果后期需要启用 SSH，只需改为 2222 等非 22 端口即可。

---

九、功能验证（快速体验）

1️⃣ 创建仓库

右上角【+】→ 新建仓库 → 填写仓库名

2️⃣ HTTP Clone & Push

git clone http://192.168.152.136:3000/admin/demo.git
cd demo
echo "hello gitea" > test.txt
git add .
git commit -m "first commit"
git push

3️⃣ Pull Request / Issue 管理

在 Web 界面即可完整体验：

• 分支管理
• 代码合并
• Issue 跟踪
• Web 在线编辑

---

十、部署总结

本次采用的方案具备如下优势：

✅ 完全私有化部署
✅ 资源占用极低（Gitea < 300MB 内存）
✅ 支持 HTTP/SSH 推送
✅ 支持 Pull Request、Issue、组织、权限控制
✅ 与 GitHub/GitLab 使用体验高度一致
✅ 非常适合中小团队、内网环境、研发平台建设

---