一、Gogs 简介

Gogs（Go Git Service）是一款基于 Go 语言开发的轻量级自助 Git 服务，旨在以最简单的方式搭建稳定、可扩展的私有 Git 仓库。其核心优势包括：

• 易安装：支持二进制分发、Docker、Vagrant 等多种部署方式，单文件即可运行
• 轻量级：最低硬件要求仅需 2 核 CPU + 512MB 内存，可运行于树莓派或 NAS 设备
• 跨平台：兼容 Linux、macOS、Windows 及 ARM 架构设备
• 功能完备：支持仓库管理、用户权限、工单系统、Wiki、Web 钩子等核心功能

适合个人开发者、小型团队或需要私有代码托管的场景，替代复杂的 GitLab，降低服务器资源占用。

二、系统要求与环境准备

1. 硬件要求

配置项	最低要求	推荐配置
CPU	1 核	2 核及以上
内存	256MB RAM	512MB RAM
存储	1GB 可用空间	根据仓库数量调整

2. 软件依赖

• 数据库：支持 MySQL 5.7+、PostgreSQL、SQLite3（推荐新手）、TiDB（通过 MySQL 协议）
• Git：服务端与客户端版本 ≥ 1.7.1
• Docker（推荐）：Docker Engine ≥ 20.10，用于快速部署

3. 环境准备

推荐使用 Linux 或 Docker 环境

三、安装步骤（Docker 部署，推荐新手）

1. 拉取 Gogs 镜像

打开终端，执行以下命令拉取官方最新镜像：

docker pull gogs/gogs:latest

当前最新稳定版为 v0.13.3，已修复高危 RCE 漏洞（CVE-2025-XXXX）

2. 启动基础容器（快速体验）

适合个人测试或单用户场景，数据持久化至本地目录：

docker run -d \
  --name=gogs \
  -p 3000:3000 \  # Web 管理界面端口  
  -p 10022:22 \    # SSH 访问端口（避免与主机 22 端口冲突）  
  -v /var/gogs:/data \  # 数据挂载目录（仓库、配置、日志等）  
  gogs/gogs:latest

3. Docker Compose 配置（生产环境推荐）

如需数据库分离（如 PostgreSQL），创建 docker-compose.yml：

version: '3'
services:
  db:
    image: postgres:15  # 推荐 PostgreSQL 15+
    environment:
      - POSTGRES_USER=gogs
      - POSTGRES_PASSWORD=your_secure_password  # 替换为安全密码
      - POSTGRES_DB=gogs
    volumes:
      - ./db-data:/var/lib/postgresql/data  # 数据库数据持久化
    restart: always

  gogs:
    image: gogs/gogs:latest
    ports:
      - "3000:3000"  # Web 端口
      - "10022:22"   # SSH 端口
    volumes:
      - ./gogs-data:/data  # Gogs 数据持久化
    depends_on:
      - db  # 依赖数据库启动
    restart: always

执行 docker-compose up -d 启动服务。

4. 安装步骤截图

图1：Docker 容器启动命令执行界面（以管理员身份运行）

四、初始化配置（Web 向导）

1. 访问配置界面

容器启动后，通过浏览器访问 http://服务器IP:3000，进入初始化向导。

2. 数据库设置

• 推荐选择 SQLite3（无需额外配置，适合新手）：
  数据库路径默认 /data/gogs/gogs.db，直接下一步。
• 如需 PostgreSQL/MySQL（适合团队使用）：
  • MySQL 需提前创建数据库：

    CREATE DATABASE gogs CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
    

  • 填写数据库主机（如 db:5432 对应 Docker Compose 中的 PostgreSQL 服务）、用户名、密码。

3. 应用基本设置

核心配置项如下（其他保持默认）：

• 应用名称：自定义服务名称（如“我的 Git 服务器”）
• 仓库根目录：默认 /data/git/gogs-repositories（无需修改）
• 运行系统用户：默认 git（Docker 环境下无需修改）
• 域名：填写服务器 IP 或域名（如 192.168.1.100）
• SSH 端口：填写宿主机映射的 SSH 端口（如 10022）
• 应用 URL：完整访问地址（如 http://192.168.1.100:3000/）

4. 配置界面截图

图2：Gogs 初始化配置界面（数据库设置与应用基本设置）

点击“立即安装”，等待 1-2 分钟，完成后自动跳转至登录页。

五、基本使用方法

1. 创建管理员账号

首次访问登录页时，点击“注册”，填写用户名（非 admin，系统会自动将首个用户设为管理员）、邮箱、密码，完成注册后即可进入管理后台。

2. 仓库创建

1. 点击右上角「+」→「新建仓库」，进入创建表单：
   • 仓库名称：必填（如 my-first-repo）
   • 可见性：选择“私有”或“公开”
   • 初始化选项：可选添加 README、.gitignore、许可证
2. 点击“创建仓库”，完成后跳转至仓库主页。

仓库创建截图

图3：Gogs 新建仓库表单界面

3. 用户管理（管理员功能）

1. 进入「管理面板」→「用户管理」→「创建用户」：
   • 填写用户名、邮箱、密码
   • 分配权限（普通用户/管理员）
2. 可通过「用户列表」管理现有用户，修改权限或禁用账号。

用户管理截图

图4：Gogs 用户管理界面（含用户列表与权限配置）

六、常见问题与解决方案

1. SSH 克隆失败

问题：执行 git clone ssh://git@服务器IP:10022/用户名/仓库名.git 提示连接拒绝。
解决：

• 检查 Docker 端口映射是否正确（宿主机 10022 → 容器 22）
• 确保防火墙开放 10022 端口（如 ufw allow 10022/tcp）

2. 数据库连接错误

问题：初始化时提示“无法连接数据库”。
解决：

• Docker Compose 环境中，数据库主机填写服务名（如 db）而非 localhost
• 手动创建数据库时确保编码为 utf8mb4

3. 数据迁移

如需迁移服务器，直接复制 Docker 挂载的 /var/gogs 或 ./gogs-data 目录，在新服务器启动容器即可。

七、安全更新与维护

1. 版本升级

Gogs 升级简单，Docker 环境下执行：

docker pull gogs/gogs:latest && docker restart gogs

2. 重要安全更新

• v0.13.3：修复存储型 XSS、路径遍历漏洞（GHSA-xh32-cx6c-cp4v）
• 建议定期查看 Gogs 官方安全公告

八、总结

Gogs 以其轻量级、易部署的特性，成为个人和小型团队私有 Git 服务的理想选择。通过 Docker 部署，仅需几分钟即可完成搭建，且资源占用极低（树莓派亦可流畅运行）。配合直观的 Web 管理界面和完善的权限控制，满足日常代码托管需求。

如需进一步扩展，可探索 Gogs 的 Web 钩子、LDAP 认证、Git LFS 等高级功能，详细文档见 Gogs 官方手册。