Gogs官方帮助文档

环境要求

• 数据库（选择以下一项）：

  • MySQL：版本 >= 5.7
  • PostgreSQL
  • MSSQL
  • TiDB（实验性支持，使用 MySQL 协议连接）
  • 或者 什么都不安装 直接使用 SQLite3

• git

  （bash）：

  • 服务端和客户端均需版本 >= 1.7.1
  • Windows 系统建议使用最新版

• SSH 服务器：

  • 如果您只使用 HTTP/HTTPS 的话请忽略此项
  • 如果您选择在 Windows 系统使用内置 SSH 服务器，请确保添加 ssh-keygen 到您的 %PATH% 环境变量中
  • 推荐 Windows 系统使用 Cygwin OpenSSH 或 Copssh
  • Windows 系统 请确保 Bash 是默认的 Shell 程序，而不是 PowerShell

安装数据库

请根据您的选择进行安装：

• MySQL（引擎：INNODB）
• PostgreSQL

注意事项 您可以使用 etc/mysql.sql 来自动创建名为 gogs 的数据库。如果您选择手动创建，请务必将编码设置为 utf8mb4。

安装其它要求

Mac OS X

假设您已经安装 Homebrew：

$ brew update
$ brew install git

Debian/Ubuntu

$ sudo apt-get update
$ sudo apt-get install git

Windows

下载并安装 Git

安装 Gogs

• 二进制安装
• 源码安装

二进制安装

目前只提供最近发布的小版本二进制下载，更多版本下载请前往 GitHub 查看。

所有的版本都支持 MySQL、PostgreSQL、MSSQL 和 TiDB（使用 MySQL 协议）作为数据库，并且均使用构建标签（build tags）cert 进行构建。需要注意的是，不同的版本的支持状态有所不同，请根据实际的 Gogs 提示进行操作。

备注

• mws 表示提供内置 Windows 服务支持，如果您使用 NSSM 请使用另外一个版本。

如何使用下载好的压缩包？

1. 解压压缩包。
2. 使用命令 cd 进入到刚刚创建的目录。
3. 执行命令 ./gogs web，然后，就没有然后了。

安装完成后可继续参照 配置与运行。

如何通过二进制升级？

1. 下载最新版的压缩包。
2. 删除当前的 templates 目录。
3. 解压压缩包并将所有内容复制粘贴到相应（当前）的位置。

源码安装

安装依赖

基本依赖

• Go 语言：版本 >= 1.8

安装 Go 语言

如果您的系统已经安装要求版本的 Go 语言，可以跳过此小节。

下载

您可以通过以下方式安装 Go 语言到 /home/git/local/go 目录：

sudo su - git
cd ~
# create a folder to install 'go'
mkdir local
# Download go (change go$VERSION.$OS-$ARCH.tar.gz to the latest release)
wget https://storage.googleapis.com/golang/go$VERSION.$OS-$ARCH.tar.gz
# expand it to ~/local
tar -C /home/git/local -xzf go$VERSION.$OS-$ARCH.tar.gz

设置环境

请设置和您系统环境对应的路径：

sudo su - git
cd ~
echo 'export GOROOT=$HOME/local/go' >> $HOME/.bashrc
echo 'export GOPATH=$HOME/go' >> $HOME/.bashrc
echo 'export PATH=$PATH:$GOROOT/bin:$GOPATH/bin' >> $HOME/.bashrc
source $HOME/.bashrc

安装 Gogs

常用的安装方式：

# 下载并安装依赖
$ go get -u github.com/gogs/gogs

# 构建主程序
$ cd $GOPATH/src/github.com/gogs/gogs
$ go build

构建 develop 分支版本

如果您想要安装 develop（或其它）分支版本，则可以通过以下命令：

$ mkdir -p $GOPATH/src/github.com/gogs
$ cd $GOPATH/src/github.com/gogs

# 请确保没有使用 “https://github.com/gogs/gogs.git”
$ git clone --depth=1 -b develop https://github.com/gogs/gogs
$ cd gogs
$ go build

测试安装

您可以通过以下方式检查 Gogs 是否可以正常工作：

cd $GOPATH/src/github.com/gogs/gogs
./gogs web

如果您没有发现任何错误信息，则可以使用 Ctrl-C 来终止运行。

使用标签构建

Gogs 默认并没有支持一些功能，这些功能需要在构建时明确使用构建标签（build tags）来支持。

目前使用标签构建的功能如下：

• sqlite3：SQLite3 数据库支持
• pam：PAM 授权认证支持
• cert：生成自定义证书支持
• miniwinsvc：Windows 服务内置支持（或者您可以使用 NSSM 来创建服务）

例如，您需要支持以上所有功能，则需要先删除 $GOPATH/pkg/{GOOS_GOARCH}/github.com/gogs/gogs 目录，然后执行以下命令：

$ go get -u -tags "sqlite pam cert" github.com/gogs/gogs
$ cd $GOPATH/src/github.com/gogs/gogs
$ go build -tags "sqlite pam cert"

安装完成后可继续参照 配置与运行。

包管理安装

以下均为第三方提供，后果自负！

Packager.io

• 当前支持 Ubuntu 14.04 + 16.04 + 18.04、CentOS 6 + 7 和 Debian 8 + 9 + 10 版本。
• 可以从 packager.io 获取到相应包管理资源（该工具的自定义配置文件有时会放置在 /etc/default/gogs）。

Arch Linux

• 基于源码构建，作者

  @fanningert

  :

  • master 分支：AUR GitHub
  • develop 分支：AUR GitHub
  • 版本：AUR GitHub

能可以到 Arch Linux Wiki entry 查看完整说明。

配置与运行

配置文件

默认配置文件

默认配置都保存在 conf/app.ini，您 永远不需要 编辑它。该文件从 v0.6.0 版本开始被嵌入到二进制中。

自定义配置文件

那么，在不允许修改默认配置文件 conf/app.ini 的情况下，怎么才能自定义配置呢？很简单，只要创建 custom/conf/app.ini 就可以！在 custom/conf/app.ini 文件中修改相应选项的值即可。

例如，需要改变仓库根目录的路径：

[repository]
ROOT = /home/jiahuachen/gogs-repositories

当然，您也可以修改数据库配置：

[database]
PASSWD = root

为什么要这么做？

乍一看，这么做有些复杂，但是这么做可以有效地保护您的自定义配置不被破坏：

• 从二进制安装的用户，可以直接替换二进制及其它文件而不至于重新编写自定义配置。
• 从源码安装的用户，可以避免由于版本管理系统导致的文件修改冲突。

运行 Gogs 服务

开发者模式

• 您需要在 custom/conf/app.ini 文件中将选项 security -> INSTALL_LOCK 的值设置为 true。

• 您可以使用超能的 make 命令：

  $ make
  $ ./gogs web
  

部署模式

脚本均放置在 scripts 目录，但请在仓库根目录执行它们

• Gogs 支持多种方式的启动：
  • 普通：只需执行 ./gogs web
  • 守护进程：详见 scripts 文件夹
• 然后访问 /install 来完成首次运行的配置工作

配置文件手册

本手册会详尽地描述有关 Gogs 配置文件的选项，帮助您更好地理解和使用 Gogs。

请记住，任何修改都是发生在 custom/conf/app.ini 自定义配置文件中，该文件的具体位置与您的设置有关。

完整的默认设置可以通过 app.ini 文件查看。如果您看到类似 %(X)s 字符，这是由 ini 提供的递归取值的特性。

概览

名称	描述
APP_NAME	应用名称，可以改成您的组织或公司名称
RUN_USER	运行应用的用户名称，我们建议您使用 git，但如果您在个人计算机上运行 Gogs，请修改为您的系统用户名称。如果没有正确设置这个值，很可能导致您的应用崩溃
RUN_MODE	鉴于性能和其它考虑，建议在部署环境下修改为 prod 模式。在您完成安装操作时，该值也会被设置为 prod

服务器 (server)

名称	描述
PROTOCOL	http 或 https
DOMAIN	服务器域名
ROOT_URL	公开的完整 URL 路径
HTTP_ADDR	应用 HTTP 监听地址
HTTP_PORT	应用 HTTP 监听端口号
UNIX_SOCKET_PERMISSION	Unix 套接字文件的权限
LOCAL_ROOT_URL	用于 Gogs 工作进程（如：SSH）回访应用的本地（DMZ）URL，一般情况下请保持默认值，除非您的 SSH 服务器节点与 HTTP 并不是同一个节点入口
DISABLE_SSH	当 SSH 功能不可用时可以禁用
START_SSH_SERVER	启用该选项来启动内置 SSH 服务器
SSH_DOMAIN	允许公用网络访问 SSH 的域名
SSH_PORT	SSH 端口号，如果不为 22 的话可以在此修改
SSH_LISTEN_HOST	内置 SSH 服务器监听的地址
SSH_LISTEN_PORT	内置 SSH 服务器监听的端口
SSH_ROOT_PATH	SSH 根目录，一般为 ~/.ssh，但必须填写为 /home/git/.ssh
REWRITE_AUTHORIZED_KEYS_AT_START	激活该选项以在应用启动时自动重写 authorized_keys 文件，该选项在使用内置 SSH 服务器时将会被自动禁用
SSH_KEY_TEST_PATH	用于测试 SSH 公钥的临时目录
SSH_KEYGEN_PATH	ssh-keygen 程序的路径，默认为 ssh-keygen 即通过系统路径查找
MINIMUM_KEY_SIZE_CHECK	指定不同类型的公钥的最小密钥大小
OFFLINE_MODE	激活该选项来禁止从 CDN 获取静态资源，同时 Gravatar 服务也将被自动禁用
DISABLE_ROUTER_LOG	激活该选项来禁止打印路由日志
CERT_FILE	HTTPS 授权文件路径
KEY_FILE	HTTPS 的密钥文件路径
STATIC_ROOT_PATH	模板文件和静态文件的上级目录，默认为应用二进制所在的位置
APP_DATA_PATH	应用内部数据的存放目录
ENABLE_GZIP	激活该选项来启用应用级别 GZIP 支持
LANDING_PAGE	未登录用户的默认首页，可以是 home 或 explore（探索页）

仓库 (repository)

名称	描述
ROOT	用户仓库存储根目录，必须为绝对路径，默认为 ~/<user name>/gogs-repositories
SCRIPT_TYPE	系统脚本类型，一般情况下均为 bash，但有些用户反应只能使用 sh
ANSI_CHARSET	当遇到无法识别的字符集时使用的默认字符集
FORCE_PRIVATE	强制要求所有新建的仓库都是私有的
MAX_CREATION_LIMIT	全局默认的每个用户可创建创建仓库上限，-1 表示无限制
PREFERRED_LICENSES	建议用户首选的授权类型
DISABLE_HTTP_GIT	激活该选项来禁止用户通过 HTTP 对 Git 仓库进行交互操作，即用户只能通过 SSH 操作
ENABLE_LOCAL_PATH_MIGRATION	激活该选项来启用本地路径迁移仓库功能。启动后默认只有管理员可以使用，普通用户必须经由管理员授权
ENABLE_RAW_FILE_RENDER_MODE	激活该选项来启用在查看原始数据时对页面进行真实渲染，例如渲染实际的 HTML 页面，有潜在安全隐患

仓库 - 编辑器 (repository.editor)

名称	描述
LINE_WRAP_EXTENSIONS	需要显示为行包装的文件名后缀，通过逗号分隔。如果是无后缀名的文件，则单独放置一个逗号，例如：.txt,

仓库 - 文件上传 (repository.upload)

名称	描述
ENABLED	激活该选项来启用仓库文件上传功能
TEMP_PATH	文件上传的临时存放目录
ALLOWED_TYPES	允许上传的文件类型（例如：”image/jpeg|image/png”），留空表示允许上传任意类型的文件
FILE_MAX_SIZE	单个上传的文件的最大体积，以 MB 为单位
MAX_FILES	单次同时上传的最多文件个数

版本发布 - 附件 (release.attachment)

名称	描述
ENABLED	激活该选项来启用版本发布附件功能
PATH	存放附件的路径
ALLOWED_TYPES	允许上传的 MIME 类型，例如 “image/jpeg|image/png”，使用 */* 允许所有类型的文件
MAX_SIZE	最大允许上传的附件体积，单位为 MB，例如 32
MAX_FILES	最大允许一次性上传的附件个数，例如 10

Markdown (markdown)

名称	描述
ENABLE_HARD_LINE_BREAK	指示是否启用硬性换行扩展
CUSTOM_URL_SCHEMES	允许被解析为链接的自定义 URL 方案，例如 git（用于 git://）和magnet（用于 magnet://）
FILE_EXTENSIONS	需要被渲染为 Markdown 格式的文件名后缀，通过逗号分隔。如果是无后缀名的文件，则单独放置一个逗号，例如：.markdown,

Smartypants (smartypants)

名称	描述
ENABLED	指示是否启用 Smartypants 扩展

HTTP (http)

名称	描述
ACCESS_CONTROL_ALLOW_ORIGIN	头信息 Access-Control-Allow-Origin 的自定义值，默认为空，即不响应此头信息

数据库 (database)

名称	描述
DB_TYPE	数据库类型，可以是 mysql、postgres、mssql 或 sqlite3
HOST	数据库主机地址与端口
NAME	数据库名称
USER	数据库用户名
PASSWD	数据库用户密码
SSL_MODE	仅限 PostgreSQL 使用
PATH	仅限 SQLite3 使用，数据库文件路径

应用管理 (admin)

名称	描述
DISABLE_REGULAR_ORG_CREATION	激活该选项来禁止普通用户（非管理员）创建组织

安全 (security)

名称	描述
INSTALL_LOCK	用于指示是否允许访问安装页面（该页面可以设置管理员帐号，因此该选项非常重要）
SECRET_KEY	全局的加密密钥，务必修改该值以确保您的服务器安全（会在每次安装时自动生成随机字符串）
LOGIN_REMEMBER_DAYS	记住登录的天数
COOKIE_USERNAME	记录用户名的 Cookie 名称
COOKIE_REMEMBER_NAME	记录用户自动登录信息的 Cookie 名称
REVERSE_PROXY_AUTHENTICATION_USER	反向代理认证用户的 Header 字段名

服务 (service)

名称	描述
ACTIVE_CODE_LIVE_MINUTES	激活码的有效期，单位为分钟
RESET_PASSWD_CODE_LIVE_MINUTES	重置密码的有效期，单位为分钟
REGISTER_EMAIL_CONFIRM	激活该选项来要求注册用户必须验证邮箱，要求已启用 Mailer
DISABLE_REGISTRATION	激活该选项来禁止用户注册功能，只能由管理员创建帐号
SHOW_REGISTRATION_BUTTON	用于指示是否显示注册按钮
REQUIRE_SIGNIN_VIEW	激活该选项来要求用户必须登录才能浏览任何页面
ENABLE_CACHE_AVATAR	激活该选项来缓存 Gravatar 的头像
ENABLE_NOTIFY_MAIL	激活该选项来发送通知邮件给关注者，例如创建 issue 时，要求已启用 Mailer
ENABLE_REVERSE_PROXY_AUTHENTICATION	激活该选项来开启反向代理用户认证，请从 #165 了解更多信息
ENABLE_REVERSE_PROXY_AUTO_REGISTRATION	激活该选项来开启反向代理用户认证的自动注册功能
DISABLE_MINIMUM_KEY_SIZE_CHECK	激活该选项来禁止检查响应类型的密钥最小长度
ENABLE_CAPTCHA	激活该选项以在用户注册时要求输入验证码

Web 钩子 (webhook)

名称	描述
TYPES	启动的 Web 钩子类型，可以是 gogs、slack、discord或dingtalk
QUEUE_LENGTH	Web钩子队列长度，如果发现部分Webhook未能成功触发，可考虑增加该值
DELIVER_TIMEOUT	发送通知的超时时间，以秒为单位
SKIP_TLS_VERIFY	指示是否允许向具有非信任证书的地址发送通知
PAGING_NUM	Web 钩子历史页面每页显示记录条数

邮件 (mailer)

名称	描述
ENABLED	启用该选项以激活邮件服务
SUBJECT_PREFIX	邮件标题的前缀
HOST	SMTP 主机地址与端口
DISABLE_HELO	禁用 HELO 操作
HELO_HOSTNAME	HELO 操作的自定义主机名
SKIP_VERIFY	不验证自签发证书的有效性
FROM	邮箱的来自地址，遵循 RFC 5322规范，可以是一个单纯的邮箱地址或者 "名字" <email@example.com> 的形式
USER	邮箱用户名
PASSWD	邮箱密码
USE_PLAIN_TEXT	使用 text/plain 作为邮件内容格式

备注：Gogs 仅支持使用 STARTTLS 的 SMTP 协议

缓存 (cache)

名称	描述
ADAPTER	缓存引擎适配器，可以为 memory、redis 或 memcache。如果您使用 redis 或 memcache，请确保使用 -tags 选项重新构建所有依赖，例如：go build -tags='redis'
INTERVAL	仅限内存缓存使用，GC 周期，单位为秒
HOST	仅限 redis 和 memcache 使用，主机地址和端口号
-	Redis：network=tcp,addr=127.0.0.1:6379,password=macaron,db=0,pool_size=100,idle_timeout=180
-	Memache：127.0.0.1:9090;127.0.0.1:9091

会话 (session)

名称	描述
PROVIDER	Session 引擎提供者，可以是 memory、file、redis 或 mysql
PROVIDER_CONFIG	如果提供者为 file，则为文件根目录；如果为其它提供者，则为主机地址和端口号
COOKIE_SECURE	激活该选项以要求所有 session 操作均通过 HTTPS
GC_INTERVAL_TIME	GC 周期，单位为秒

图片 (picture)

名称	描述
AVATAR_UPLOAD_PATH	存放用户上传头像的目录
GRAVATAR_SOURCE	可以是 gravatar、duoshuo 或任何 URL，例如：http://cn.gravatar.com/avatar/
DISABLE_GRAVATAR	激活该选项来仅使用本地头像
ENABLE_FEDERATED_AVATAR	激活该选项来启用 Federated 头像服务（http://www.libravatar.org），当 Gravatar 被禁用时此选项无法生效

附件 (attachment)

名称	描述
ENABLED	激活该选项以允许用户上传附件
PATH	存放附件的路径
ALLOWED_TYPES	允许上传的 MIME 类型，例如 “image/jpeg|image/png”，使用 */* 允许所有类型的文件
MAX_SIZE	最大允许上传的附件体积，单位为 MB，例如 4
MAX_FILES	最大允许一次性上传的附件个数，例如 5

时间 (time)

名称	描述
FORMAT	指定日期的输出格式，默认为 RFC1123，其它可选的格式为 ANSIC、UnixDate、RubyDate、RFC822、RFC822Z、RFC850、RFC1123、RFC1123Z、RFC3339、RFC3339Nano、Kitchen、Stamp、StampMilli、StampMicro 和 StampNano。访问 http://golang.org/pkg/time/#pkg-constants 查看详情

日志 (log)

名称	描述
ROOT_PATH	日志文件的根目录
MODE	日志记录模式，默认为 console。如果想要开启多模式，请使用逗号分割，例如："console, file"
LEVEL	基本日志级别，默认为 Trace

日志 - 控制台 (log.console)

名称	描述
LEVEL	控制台日志级别，留空则继承父值

日志 - 文件 (log.file)

名称	描述
LEVEL	文件日志级别，留空则继承父值
LOG_ROTATE	激活该选项以启用日志文件自转
DAILY_ROTATE	激活该选项以进行日常自转
MAX_SIZE_SHIFT	自转需要达到的最大文件体积，使用位左移，默认为 28 即 1 << 28，表示 256MB
MAX_LINES	自转需要达到的最大文件行数，默认为 1000000
MAX_DAYS	保留自转文件的最长期限，默认为 7 天后删除

日志 - Slack (log.slack)

名称	描述
LEVEL	Slack 日志级别，留空则继承父值
URL	Slack Web 钩子 URL

日志 - Discord (log.discord)

名称	描述
LEVEL	Discord 日志级别，留空则继承父值
URL	Discord Web 钩子 URL
USERNAME	在 Web 钩子中显示的用户名

Cron (cron)

名称	描述
ENABLED	激活该选项以允许周期性运行 Cron 任务
RUN_AT_START	激活该选项以允许在启动时执行 Cron 任务

Cron - 更新镜像 (cron.update_mirrors)

名称	描述
SCHEDULE	定时更新仓库镜像的 Cron 语法，例如：@every 1h

Cron - 仓库健康检查 (cron.repo_health_check)

名称	描述
SCHEDULE	定时进行仓库健康检查的 Cron 语法，例如：@every 24h
TIMEOUT	仓库健康检查超时的定义语法，例如：60s
ARGS	git fsck 命令的参数，例如：--unreachable --tags

Cron - 仓库统计检查 (cron.check_repo_stats)

名称	描述
RUN_AT_START	激活该选项以在启动时执行仓库统计检查
SCHEDULE	定时进行仓库统计检查的 Cron 语法，例如：@every 24h

Cron - 仓库归档清理 (cron.repo_archive_cleanup)

名称	描述
RUN_AT_START	激活该选项以在启动时执行仓库归档清理
SCHEDULE	定时进行仓库归档清理的 Cron 语法，例如：@every 24h
OLDER_THAN	仓库归档的文件有效期，过期的归档将被清理，例如：24h

Git (git)

名称	描述
DISABLE_DIFF_HIGHLIGHT	激活该选项以禁用行内差异高亮
MAX_GIT_DIFF_LINES	差异对比页面单个文件显示的最大行数
MAX_GIT_DIFF_LINE_CHARACTERS	差异对比页面单行显示的最大字符数
MAX_GIT_DIFF_FILES	差异对比页面文件显示的最多个数
GC_ARGS	git gc 命令的参数，例如：--aggressive --auto

Git - 超时 (git.timeout)

名称	描述
MIGRATE	仓库迁移操作超时，默认为 600 秒
MIRROR	仓库镜像同步操作超时，默认为 300 秒
CLONE	仓库克隆操作超时，默认为 300 秒
PULL	仓库拉取操作超时，默认为 300 秒
GC	仓库垃圾回收操作超时，默认为 60 秒

UI (ui)

名称	描述
EXPLORE_PAGING_NUM	探索页面每页显示仓库的数量
ISSUE_PAGING_NUM	每页显示工单（Issue）的数量（应用到所有以列表形式显示工单的页面）
FEED_MAX_COMMIT_NUM	一条最新活动中显示代码提交（Commit）的最大数量
THEME_COLOR_META_TAG	被用于 Android >= 5.0 版本 “theme-color” 标记的值，无效的值将被忽略并使用默认值（查看详情）
MAX_DISPLAY_FILE_SIZE	显示到页面的最大文件体积（Byte）

UI - Admin (ui.admin)

名称	描述
USER_PAGING_NUM	用户管理页面每页显示记录条数
REPO_PAGING_NUM	仓库管理页面每页显示记录条数
NOTICE_PAGING_NUM	系统提示管理页面每页显示记录条数
ORG_PAGING_NUM	组织管理页面每页显示记录条数

Prometheus (prometheus)

名称	描述
ENABLED	激活该选项以启用 Prometheus 监控信息，默认为 true
ENABLE_BASIC_AUTH	激活该选项以启用 HTTP 基本认证保护监控信息数据，默认为 false
BASIC_AUTH_USERNAME	HTTP 基本认证的用户名
BASIC_AUTH_PASSWORD	HTTP 基本认证的密码

其他 (other)

名称	描述
SHOW_FOOTER_BRANDING	激活该选项以在页脚显示 Gogs 推广信息
SHOW_FOOTER_VERSION	激活该选项以在页脚显示 Gogs 版本信息
SHOW_FOOTER_TEMPLATE_LOAD_TIME	激活该选项以在页脚显示 Gogs 模板加载时间