Gogs 本地开发环境搭建指南：依赖安装、数据库初始化与 moon run gogs:dev 开发循环

本文基于 Gogs 仓库官方的 本地开发文档，完整覆盖从环境准备、依赖安装、PostgreSQL 数据库初始化，到 custom/conf/app.ini 数据库配置与 moon run gogs:dev 一键热重启开发服务器的全部流程，并结合 moon.yml、internal/conf/conf.go 等源码印证每一步背后的实际行为。读完并按步骤操作后，你可以在 macOS 或 Ubuntu 上搭建起一个带自动重编译、静态资源开发代理和离线模式的 Gogs 本地开发环境。

环境与总体要求

Gogs 以单一二进制的方式构建和运行，设计目标是跨平台，因此你可以在任意主流操作系统上进行开发。官方文档列出的开发依赖如下：

• Git（v1.8.3 或更高）
• Go（v1.20 或更高；注意当前仓库 go.mod 中 go 指令声明为 1.26.0，要在当前代码树上直接构建，实际应使用不低于该声明的新版工具链）
• Less.js（编译 public/less/ 下的样式）
• Moon（moonrepo.dev，任务运行器，moon.yml 定义了全部开发/构建任务）
• goimports（Go 代码格式化）
• go-mockgen（接口 mock 代码生成；仓库根目录的 mockgen.go 与 mockgen.yaml 即其生成入口配置）
• 数据库（任选其一，官方文档以 PostgreSQL 为例）：
  • PostgreSQL（v9.6 或更高）
  • MySQL（v5.7 或更高，需 ENGINE=InnoDB）
  • MariaDB（v10.3 或更高，TYPE = mysql）
  • SQLite3

从 go.mod 可以确认，Gogs 同时集成了 PostgreSQL（gorm.io/driver/postgres）、MySQL（gorm.io/driver/mysql）与 SQLite（github.com/glebarez/sqlite，纯 Go 实现，无需 CGO）三种驱动，与文档所列数据库选项一一对应。

Step 1：安装依赖

macOS

1. 先安装 Homebrew。
2. 安装依赖：

brew install go postgresql git npm moon portless
portless trust
npm install -g less
npm install -g less-plugin-clean-css
go install github.com/derision-test/go-mockgen/cmd/go-mockgen@v1.3.3
go install golang.org/x/tools/cmd/goimports@latest

其中 portless trust 的作用是把本地 CA 加入系统信任库，让 https://gogs.localhost 在没有浏览器警告的情况下正常工作；moon run gogs:dev 任务会启动这个代理并自动注册路由。这一点在 moon.yml 的 portless 任务中可以得到印证：该任务会执行 portless alias gogs 3000 --force、portless proxy start，并用 awk 脚本把 DOMAIN = gogs.localhost 和 EXTERNAL_URL = https://gogs.localhost/ 注入到 .bin/custom/conf/app.ini 的 [server] 段中。

3. 配置 PostgreSQL 自动启动：

brew services start postgresql

4. 确保 psql（PostgreSQL 命令行客户端）在 $PATH 中。Homebrew 默认不会把它放进去；brew info postgresql 输出的 "Caveats" 部分会给出需要执行的 PATH 设置命令，或者直接使用下面的命令（可能需要根据你的 Homebrew 前缀——下例为 /usr/local——和 shell——下例为 bash——做调整）：

hash psql || { echo 'export PATH="/usr/local/opt/postgresql/bin:$PATH"' >> ~/.bash_profile }
source ~/.bash_profile

Ubuntu

1. 添加包仓库（NodeSource）：

curl -sL https://deb.nodesource.com/setup_10.x | sudo -E bash -

2. 更新仓库索引：

sudo apt-get update

3. 安装依赖：

sudo apt install -y make git-all postgresql postgresql-contrib golang-go nodejs
npm install -g less
go install github.com/derision-test/go-mockgen/cmd/go-mockgen@v1.3.3
go install golang.org/x/tools/cmd/goimports@latest

4. 安装 Moon 任务运行器（参见 moonrepo.dev 的安装说明）。
5. 配置开机自启服务：

sudo systemctl enable postgresql

Step 2：初始化数据库

你需要一个全新的 Postgres 数据库，以及一个对该数据库拥有完全所有权的数据库用户。

1. 为当前 Unix 用户创建数据库。Linux 用户先进入 postgres 用户的 shell：

# For Linux users, first access the postgres user shell
sudo su - postgres

然后执行：

createdb

2. 创建 Gogs 数据库用户并设置密码：

createuser --superuser gogs
psql -c "ALTER USER gogs WITH PASSWORD '<YOUR PASSWORD HERE>';"

3. 创建 Gogs 数据库：

createdb --owner=gogs --encoding=UTF8 --template=template0 gogs

说明：--owner=gogs 保证 gogs 用户对该库拥有所有权，--template=template0 使用空模板库以确保编码干净，--encoding=UTF8 与 Gogs 对 UTF-8 数据的要求一致。

Step 3：获取代码

通常不需要完整克隆历史，官方文档建议把 --depth 设为 10：

git clone --depth 10 https://gitcode.com/GitHub_Trending/go/gogs

注意：仓库已启用 Go Modules，请克隆到 $GOPATH 之外的任意位置。

Step 4：配置数据库设置

在仓库内创建 custom/conf/app.ini 文件并写入以下配置（custom/ 目录下的内容用于覆盖仓库内置的默认文件，文档说明该目录被 .gitignore 排除，不会污染工作区）：

[database]
TYPE = postgres
HOST = 127.0.0.1:5432
NAME = gogs
USER = gogs
PASSWORD = <YOUR PASSWORD HERE>
SSL_MODE = disable

自定义配置机制的源码佐证

自定义配置的加载逻辑位于 internal/conf/conf.go：

• 若未显式指定 customConf，框架会回退到默认位置 <WORK DIR>/custom/conf/app.ini，这正是文档要求把文件放在 custom/conf/app.ini 的原因；
• 该路径被解析为绝对路径后赋值给包级变量 conf.CustomConf（声明见 internal/conf/static.go）；
• 若文件不存在，Init 会直接返回 "custom config not found" 错误，提示先完成首次安装配置——所以 Step 4 必须在启动服务之前完成。

conf.CustomConf 并不只是启动时读取一次：从源码看，SSH 服务的子进程（internal/ssh/ssh.go 中以 --config= 参数传给 gogs serv key-<id>）、仓库 hook 脚本模板（internal/database/repo.go）以及 SSH 克隆 URL 的生成（internal/database/ssh_key.go）都会引用该路径，保证整条链路使用同一份覆盖后的配置。

Step 5：启动开发服务器

moon run gogs:dev

该命令会启动 Web 服务器，并且在任何 Go 源文件发生变化时自动重新编译并重启服务。

注意：如果你修改了 conf/、templates/ 或 public/ 目录下的任何文件，之后务必重新运行 moon run gogs:dev。

gogs:dev 任务实际做了什么

对照仓库根目录的 moon.yml，dev 任务本身是一个 persistent 的 noop 占位任务（runInCI: false，不在 CI 中执行），它的价值在于通过 deps 拉起一整套并行子任务：

依赖任务	定义位置	实际行为
build	moon.yml	go build -v -trimpath，通过 -ldflags 注入 BuildTime 与 BuildCommit 到 internal/conf 包变量，输出二进制到 .bin/gogs。其 inputs 包含 @group(assets)（即 conf/**、public/**、templates/**），这些嵌入资源变更会触发重编译
server	moon.yml	执行 cd .bin && ./gogs web，gogs web 子命令的入口位于 cmd/gogs/serv.go
web:dev	web/moon.yml	在 web/ 子工作区执行 pnpm run dev，即启动 Vite 前端开发服务器
portless	moon.yml	注册 gogs.localhost 别名、启动 HTTPS 代理，并改写 .bin/custom/conf/app.ini 的 [server] 段（DOMAIN/EXTERNAL_URL）

这里有一个值得注意的构建细节：非 prod 标签构建下，public/web_dev.go 中的 WebAssets 是一个空的 embed.FS（//go:build !prod），注释明确说明开发模式下它为空、相关请求会被代理到运行中的 Vite 服务器；生产构建（build-prod 使用 -tags prod）则通过 web:build 把 web/ 的产物嵌入 public/dist。因此开发时修改前端组件无需重编 Go 二进制，但修改 conf/、templates/、public/ 下的嵌入式资源时，仍建议按文档提示重新运行 moon run gogs:dev 以触发 build 任务的资源嵌入。

其他实用技巧

从磁盘加载 HTML 模板与静态文件

当你正在积极修改 HTML 模板和静态文件时，可以启用以下配置，避免每次改动 templates/（文档中写作 template/）和 public/ 目录下的文件后都要重新编译并重启 Gogs：

RUN_MODE = dev

[server]
LOAD_ASSETS_FROM_DISK = true

源码层面可以印证这一开关的真实影响：配置项声明于 internal/conf/static.go，判断逻辑分布在 Web 路由层（cmd/gogs/internal/web/web.go 中多处 if conf.Server.LoadAssetsFromDisk 分支）与邮件模板层（internal/email/email.go：开启后从工作目录的 templates/mail 读取邮件模板）。管理员后台的 templates/admin/config.tmpl 中也有对应的状态显示项。

离线开发

有时你需要开发 Gogs，但恰好坐在飞机、火车上，或者在海滩——总之没有 WiFi。你可能会对着天空挥拳怒吼："我们都能把人送上月球了，为什么没网就开发不了一个高质量的 Git 托管服务？"不过把手放回车键上，别发愁：在 custom/conf/app.ini 中设置以下配置即可在无网络环境下开发：

[server]
OFFLINE_MODE = true

该配置项在 internal/conf/static.go 中声明为 OfflineMode 布尔字段，并在 internal/conf/conf.go 处被读取参与运行时分支——从源码结构看，它控制的是 Gogs 访问外部资源的默认代码路径，从而让服务在断网时仍可正常启动和本地调试。

小结

按官方文档的五步走流程：装好 Go/Git/Less/Moon/goimports/go-mockgen 与 PostgreSQL 依赖，初始化 gogs 用户与数据库，浅克隆（--depth 10）代码到 $GOPATH 之外，写入 custom/conf/app.ini，最后用 moon run gogs:dev 拉起"构建 + 服务 + 前端开发代理 + 本地 HTTPS 域名"的完整开发循环；再用 LOAD_ASSETS_FROM_DISK 与 OFFLINE_MODE 两个开关分别覆盖"模板/静态文件高频修改"和"断网开发"两类场景。所有命令均可直接复制执行，所有机制均可在 moon.yml、internal/conf/ 等源码路径中逐条对照验证。