CentOS 7/8下Gogs轻量级Git服务部署全流程

Gogs这个名字常年在自建Git服务圈子里出现。它是个用Go写的轻量级Git托管平台整个服务就是一个可执行文件跑起来占用的内存比GitLab小一个数量级特别适合那种二三十人以内的小团队、内网研发环境、或者个人VPS上临时搭一个代码仓库。今天这篇就完整记录一下我在CentOS 7.9和CentOS 8.x上部署Gogs的全过程从装依赖、选数据库、写配置到用systemd托管进程、再用Nginx反代出去整个流程走通之后你就能得到一个正经能用的Git服务。我一开始也被各种“一键部署”脚本坑过后来直接改用官方二进制包手动部署过程反而更可控。下面所有步骤都基于我实际操作的命令CentOS 7.9和8.x通用部分命令在9上可能会有小差异但核心思路不变。1. 动手之前Gogs是什么什么场景用它1.1 为什么我选Gogs而不是GitLabGitLab功能确实全但你要知道它是个“全家桶”Ruby写的服务PostgreSQL、Redis、Sidekiq、Prometheus这一串全得跟着装上普通2核4G的机器跑起来都吃力内存动不动吃满。Gogs不一样它本身就是一个Go编译出来的二进制文件官方给的最低要求非常低512MB内存的机器也能带起来。我说的“轻量”不是指功能砍到没法用。Gogs核心功能很完整仓库托管、Issue、Pull Request、WebHook、组织管理、SSH和HTTP两种clone方式、内置CI集成日常团队协作够用了。而且界面清爽没有一堆花里胡哨的按钮内网用户上手成本低。所以如果你只是给一个三五人的小组搞个代码托管或者自己折腾一个备份仓库Gogs是性价比最高的选择。如果你需要几百上千人、复杂权限体系、流水线、Code Review规则那直接上GitLab Enterprise或Gitea商业方案别难为Gogs。1.2 部署前的环境准备Gogs官方支持的操作系统很广CentOS 7、CentOS 8、Debian、Ubuntu都行。我这边测试环境是两个一台CentOS 7.9一台CentOS 8.5都是最小化安装没有图形界面。先确认系统版本和架构cat /etc/redhat-release uname -m我实测的版本输出分别是CentOS Linux release 7.9.2009 (Core) x86_64再确认内存和磁盘足够。Gogs本身只占100MB左右内存但仓库多了磁盘容易吃紧。建议至少准备20GB可用空间如果只是放几个小项目5GB也能跑。CentOS 7和8都已经进入EOL阶段默认源基本不可用了如果遇到yum装不了包可以先替换成国内可用的镜像源源具体替换方法网上有很多这里不展开。替换完再执行yum update -y这一步不是必须但建议做至少把基础安全补丁打上。2. 基础环境安装和目录规划2.1 安装Git和相关工具Gogs本身虽然是用Go写的自包含程序但它管理仓库时还是会调用系统里的git命令。所以系统里必须装git而且版本不能太老。CentOS 7默认的git是1.8.3说实话有点老但处理常见的push、pull、分支合并是够用的。CentOS 8自带的git是2.x要好很多。如果你对git功能要求高比如要用worktree、更完整的partial clone那还是建议用高版本。先装基础工具yum install -y git curl wget sqlite-develsqlite-devel这个包不是必须但是如果后面要用SQLite数据库最好装上有备无患。curl和wget用来下载Gogs安装包git是运行时依赖。如果你用的是CentOS 7而且真的想要新一点的git可以用源码编译但我不建议初次部署就把时间耗在编译git上。Gogs官网的最低要求没卡git版本1.8在实际使用中也没碰到过兼容问题。2.2 创建专用用户和目录结构生产环境最大的忌讳是直接用root跑服务。Gogs官方文档里也明确说了要用一个独立的系统用户运行。我习惯创建一个名为git的系统用户useradd --system --user-group --home /home/git git参数解释一下--system表示创建系统账户--user-group会自动建一个同名的git组--home指定家目录后面存仓库目录用。然后创建Gogs的部署目录和仓库目录mkdir -p /opt/gogs mkdir -p /home/git/gogs-repositories chown -R git:git /opt/gogs /home/git为什么仓库目录单独放在/home/git/gogs-repositories而不是放在/opt/gogs里面因为我习惯把“程序二进制”和“数据”分开。升级的时候只需要替换程序目录仓库数据不动备份也更清晰。如果你希望仓库放在数据盘也可以把家目录或仓库目录指到数据盘挂载点比如/data/git/repos以后扩容更方便。3. 数据库选型SQLite还是MySQL3.1 两种方案的取舍Gogs支持SQLite、MySQL、PostgreSQL、MSSQL等数据库。对小团队来说最常见的选择就是SQLite和MySQL/MariaDB我把区别整理成一张表对比项SQLiteMySQL/MariaDB部署成本零配置直接用需要额外装数据库服务内存占用最低多占用200~300MB并发能力弱适合低并发强适合多人同时操作备份复杂度直接复制文件mysqldump或物理备份适合场景个人、三五人小团队正式团队有运维能力我的建议很直接如果只是个人用或者小组不超过5个人直接用SQLite省心。如果团队有二三十人或者你希望以后数据好迁移、备份好管理就上MySQL或MariaDB。3.2 用MariaDB初始化数据库我这里用MariaDB举例因为CentOS 7自带MariaDB安装简单兼容MySQL协议。yum install -y mariadb-server systemctl enable --now mariadb然后执行安全初始化mysql_secure_installation按提示设置root密码关掉匿名用户关掉测试库基本都选y就行。接着登录数据库创建Gogs专用的库和账号mysql -u root -p执行SQLCREATE DATABASE IF NOT EXISTS gogs DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; CREATE USER gogs127.0.0.1 IDENTIFIED BY 这里换成你自己的强密码; GRANT ALL PRIVILEGES ON gogs.* TO gogs127.0.0.1; FLUSH PRIVILEGES; EXIT;这里有个细节创建用户时我用的host是127.0.0.1而不是localhost因为Java/Go的数据库驱动走TCP连接时如果用localhost可能会走socket文件权限匹配容易踩坑。之前我就因为这个问题被坑过一次后来统一用127.0.0.1一次过。用utf8mb4而不是utf8是为了兼容emoji和部分生僻字。虽然代码提交信息里出现emoji的概率不高但万一有呢别给自己埋坑。3.3 直接用SQLite的零配置方案如果你决定用SQLite那数据库这步直接跳过Gogs安装向导里选SQLite3程序会在指定目录下生成gogs.db文件。唯一的注意事项是这个db文件所在目录必须对运行用户git可写。否则安装页面会报unable to open database file。我部署时习惯把SQLite文件放在/opt/gogs/data目录下在后面的配置里设置好PATH路径就行。4. 下载Gogs并完成基础配置4.1 下载Gogs二进制包到Gogs的GitHub Releases页面找最新版Linux amd64的压缩包。为了避免我写死版本号导致你复制的时候失效这里直接给通用下载思路cd /tmp wget https://github.com/gogs/gogs/releases/download/v0.13.0/gogs_0.13.0_linux_amd64.tar.gz如果下载慢可以去找国内加速镜像把下载地址换成镜像地址。理论上只要拿到相同的tar.gz包即可。解压tar -xzvf gogs_0.13.0_linux_amd64.tar.gz -C /opt/解压出来会多一个/opt/gogs目录里面结构大概是/opt/gogs/gogs /opt/gogs/custom/ /opt/gogs/log/ /opt/gogs/scripts/给gogs文件加执行权限并把整个目录归属给git用户chown -R git:git /opt/gogs chmod x /opt/gogs/gogs4.2 手工写配置文件app.iniGogs支持通过浏览器安装向导生成配置也支持提前手工写好custom/conf/app.ini。我的习惯是手工写因为用脚本自动化部署时更方便而且不会因为填错表单反复重启。先创建目录mkdir -p /opt/gogs/custom/conf然后编辑/opt/gogs/custom/conf/app.iniAPP_NAME Gogs RUN_USER git RUN_MODE prod [server] PROTOCOL http DOMAIN git.example.com HTTP_ADDR 127.0.0.1 HTTP_PORT 3000 ROOT_URL http://git.example.com/ DISABLE_SSH false SSH_PORT 2222 START_SSH_SERVER false [database] TYPE mysql HOST 127.0.0.1:3306 NAME gogs USER gogs PASSWD 你的数据库密码 SSL_MODE disable PATH /opt/gogs/data/gogs.db [repository] ROOT /home/git/gogs-repositories DEFAULT_BRANCH main [service] DISABLE_REGISTRATION true REQUIRE_SIGNIN_VIEW true几个关键点RUN_USER git这个必须和运行用户一致别用root。HTTP_ADDR 127.0.0.1表示Gogs只在本机监听后续靠Nginx转发安全一些。如果你不想用Nginx想直接IP:3000访问就把HTTP_ADDR改成0.0.0.0同时防火墙放行3000端口。DOMAIN和ROOT_URL一定要填对外访问的域名或IP不然页面上生成的仓库clone地址会是127.0.0.1别人根本连不上。SSH_PORT 2222这里我用的是自定义SSH端口如果你服务器SSH就是22就写22。这个配置会直接影响Gogs页面上显示的SSH clone地址必须写对。4.3 第一次启动验证配置写完后先别急着配systemd用前台方式启动一次看看日志有没有报错cd /opt/gogs sudo -u git /opt/gogs/gogs web如果一切正常会看到类似监听127.0.0.1:3000的日志。这时浏览器访问http://服务器IP:3000能打开页面。注意cd /opt/gogs这步很重要因为Gogs默认会找当前目录下的custom/conf/app.ini。如果你在别的目录执行/opt/gogs/gogs web它可能根本读不到你的配置。到时候service文件里也要把WorkingDirectory设置成/opt/gogs。确认正常后CtrlC停掉进程继续下一步。5. 用systemd守护Gogs进程5.1 编写service文件裸跑Gogs关了终端它就没了生产环境必须交给systemd托管。创建一个service文件vim /etc/systemd/system/gogs.service内容如下[Unit] DescriptionGogs Afternetwork.target Wantsnetwork.target [Service] Usergit Groupgit WorkingDirectory/opt/gogs ExecStart/opt/gogs/gogs web --config /opt/gogs/custom/conf/app.ini Restartalways RestartSec5 EnvironmentUSERgit EnvironmentHOME/home/git [Install] WantedBymulti-user.target然后是重载并启动systemctl daemon-reload systemctl enable --now gogs systemctl status gogs看到active (running)就成功了。查看日志用journalctl -u gogs -f这里解释一下为什么EnvironmentHOME/home/git。之前遇到过一个问题systemd启动的进程默认HOME可能是/root导致git用户下执行某些命令时读取不到家目录配置。显式指定HOME后SSH key读写、缓存目录都正常了。5.2 防火墙与安全组放行生产服务器大概率开着防火墙CentOS 7默认是firewalld。我建议先用Nginx做反代所以只需要放行HTTP/HTTPS端口不需要直接暴露3000。但如果只是内网测试直接放行3000也简单firewall-cmd --permanent --add-port3000/tcp firewall-cmd --reload如果用了Nginx反代放行80和443firewall-cmd --permanent --add-servicehttp firewall-cmd --permanent --add-servicehttps firewall-cmd --reload另外要确认云厂商安全组也放行了对应端口不然本地防火墙全开也连不上。这个坑我踩过一次本地怎么测都通换外网就超时最后查半天发现是安全组没加规则。6. 用Nginx反向代理对外提供服务6.1 为什么要套一层NginxGogs本身支持HTTP、HTTPS直接跑但实际部署我还是建议在前面加个Nginx。原因有三一是Nginx处理静态资源、并发连接的能力强能扛住比Gogs单进程更高的访问量。二是方便统一管理证书。Gogs虽然可以配置TLS证书但证书续期、多域名配置、日志切割这些还是Nginx更顺手。三是能隐藏Gogs实际监听端口。Gogs跑在3000外面只开80/443安全性和整洁度都更好。6.2 Nginx配置实战安装Nginxyum install -y nginx systemctl enable --now nginx如果CentOS 7的默认源没有nginx就得先装epelyum install -y epel-release然后创建虚拟主机配置vim /etc/nginx/conf.d/gogs.conf内容server { listen 80; server_name git.example.com; client_max_body_size 100m; location / { proxy_pass http://127.0.0.1:3000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }client_max_body_size 100m这个很重要。默认Nginx上传大小限制是1MB如果你通过Web页面上传大压缩包或者push较大的二进制文件不调这个一定报413。proxy_set_header这些头也必须带不然Gogs拿到的请求地址全是127.0.0.1页面上生成的clone链接就可能不对。然后检查配置并重载nginx -t systemctl reload nginx如果你还要上HTTPS在同一个server块里配置证书路径监听443或者用certbot自动申请证书这里不再展开。还要注意SELinux。CentOS默认开启SELinuxNginx往本机3000端口转发时需要放行setsebool -P httpd_can_network_connect 1如果不做这步你会看到Nginx能启动但访问时一直502。这一点是我在CentOS上遇到过的最多的问题。6.3 SSH访问的配置补充Gogs除了HTTP clone还可以走SSH协议。如果你的用户习惯用SSH方式clone还需要让git用户能通过SSH登录。最简单的方式直接复用系统的sshd端口22。如果你服务器22端口被占用或者为了安全改了自定义端口要把Gogs配置文件里的SSH_PORT改成和sshd一致同时防火墙放行该端口。然后在Gogs网页后台的个人设置里把用户本地的公钥填进去。最后clone地址会是类似gitgit.example.com:username/repo.git这里有个常见误区如果你改了sshd端口比如改成2222但Gogs页面里SSH_PORT还写的22用户复制出来的地址就是错的连不上。还有一点如果你不想通过系统SSH服务暴露git用户也可以用Gogs内置的SSH服务器把配置文件里START_SSH_SERVER设为true并指定SSH_PORT然后这个端口单独给Gogs用。但这种情况需要确保系统ssh和Gogs内置ssh端口不冲突我一般不推荐除非你对Linux用户管理很熟练。7. 备份、升级与常见问题速查7.1 备份策略与脚本Gogs最核心的数据有三块数据位置配置文件/opt/gogs/custom/仓库数据/home/git/gogs-repositories/数据库SQLite文件或MySQL库只要这三样都在换一台机器也能完整恢复。我自己写了个简单的备份脚本放/usr/local/bin/backup_gogs.sh#!/bin/bash BACKUP_DIR/backup/gogs DATE$(date %Y%m%d) mkdir -p $BACKUP_DIR/$DATE # 备份配置 cp -r /opt/gogs/custom $BACKUP_DIR/$DATE/ # 备份仓库 cp -r /home/git/gogs-repositories $BACKUP_DIR/$DATE/ # 备份数据库这里以MySQL为例 mysqldump -h127.0.0.1 -ugogs -p数据库密码 gogs $BACKUP_DIR/$DATE/gogs.sql # 打包 tar -czf $BACKUP_DIR/gogs-$DATE.tar.gz -C $BACKUP_DIR/$DATE . rm -rf $BACKUP_DIR/$DATE find $BACKUP_DIR -name *.tar.gz -mtime 30 -delete如果用SQLite备份时不要直接cp建议用sqlite3的备份命令sqlite3 /opt/gogs/data/gogs.db .backup /backup/gogs/gogs.db因为SQLite在运行时直接复制文件可能得到一个不一致的副本尤其正在写入时。最后加个定时任务crontab -e 0 2 * * * /bin/bash /usr/local/bin/backup_gogs.sh /dev/null 21每天凌晨2点自动备份一次保留30天。7.2 升级流程升级Gogs不难但要按顺序走别直接覆盖custom目录。我的流程是这样systemctl stop gogs cp -r /opt/gogs/custom /tmp/custom_backup # 下载新版压缩包并解压到临时目录 cd /tmp wget 新版gogs包 tar -xzvf gogs_new.tar.gz # 只替换二进制文件 cp /tmp/gogs/gogs /opt/gogs/gogs chown git:git /opt/gogs/gogs systemctl start gogs启动后看下日志Gogs会自动执行数据库迁移一般不需要手动改表结构。升级前千万备份尤其是custom/conf/app.ini。我有一次图省事全部覆盖结果配置被新版默认模板顶掉服务起不来耽误了不少时间。7.3 常见问题排查现象可能原因解决办法页面无法访问服务没起来、防火墙、安全组systemctl status gogs检查日志和firewall-cmdNginx访问502SELinux拦截setsebool -P httpd_can_network_connect 1clone地址不对DOMAIN/ROOT_URL配置错误修改app.ini后重启Web上传大文件报413Nginx默认限制1MB设置client_max_body_size数据库连接失败密码错、host不对、数据库没启动逐项检查用命令行连一次push时卡住或超时网络代理、大文件、SSH超时调整Nginx proxy_read_timeout检查带宽以root启动后仓库权限错RUN_USER和实际运行用户不一致全目录chown给git再用git用户启动收发邮件不工作SMTP配置不对检查app.ini里的mailer段和日志这些基本覆盖了常见问题。我个人的体会是Gogs部署本身并不复杂真正容易出问题的都是周边环境SELinux、防火墙、配置文件里的域名写错这几个坑占了我遇到问题的八成。如果你照着这篇走一遍还是没跑起来优先看日志Gogs的日志都在/opt/gogs/log/目录下比瞎猜准得多。最后再提一个实用习惯在做任何配置修改之前先备份一遍custom目录和数据库。改完重启验证没问题再该干嘛干嘛。Git服务最重要的不是跑起来是数据别丢。