Sourcehut 常用命令与运维详解

本篇是 Sourcehut 系列的运维篇：面向已按《Sourcehut 0.88.9 + git.sr.ht 0.102.8 Ubuntu 22.04 安装指南》完成单机最小可用集（meta.sr.ht 0.88.9 + git.sr.ht 0.102.8，Ubuntu 22.04.5）的管理员，覆盖服务管理、用户管理、数据库与仓库存储的备份恢复、版本升级与故障排查。配置项含义见《Sourcehut 配置参数详解》，选型背景见《Sourcehut 介绍与选型指南》。

一、服务管理：四个进程一个网关

1.1 单元清单与启停

最小可用集共 4 个常驻服务 + 1 个按需 CGI 网关：

单元	端口	角色
meta.sr.ht.service	5000	认证中心 Web（gunicorn）
meta.sr.ht-api.service	5100	认证中心 GraphQL API（Go）
git.sr.ht.service	5001	代码托管 Web（gunicorn）
git.sr.ht-api.service	5101	代码托管 GraphQL API（Go）
fcgiwrap.socket	—	git smart-HTTP clone 的 CGI 网关（按需拉起）

sudo systemctl start meta.sr.ht-api meta.sr.ht git.sr.ht-api git.sr.ht
sudo systemctl stop  git.sr.ht git.sr.ht-api meta.sr.ht meta.sr.ht-api
sudo systemctl restart meta.sr.ht       # 改 ini 后按需重启（见配置篇第七节）

1.2 探活矩阵

一屏确认全链路（实测输出）：

$ for u in "meta.sr.ht.local/" "git.sr.ht.local/"; do
    curl -s -o /dev/null -w "$u -> %{http_code}\n" -H "Host: ${u%%/*}" http://127.0.0.1/${u#*/}
  done
meta.srht.local/ -> 200
git.srht.local/ -> 200

$ curl -s -o /dev/null -w "meta-api %{http_code}\n" -X POST http://127.0.0.1:5100/query
meta-api 401
$ curl -s -o /dev/null -w "git-api  %{http_code}\n" -X POST http://127.0.0.1:5101/query
git-api  401

判读要点：Web 端 200 为健康；API 端 401 才是健康（/query 要求内部认证头，401 表示服务在正常拒绝匿名请求；404/000 才是异常）。

1.3 进程与日志

$ ps -eo pid,cmd | grep -E "gunicorn|sr.ht-api" | grep -v grep
  7826 /opt/venv/bin/python3 /opt/venv/bin/gunicorn metasrht.app:app ...
 15577 /usr/local/bin/meta.sr.ht-api
 19881 /usr/local/bin/git.sr.ht-api
$ sudo journalctl -u meta.sr.ht -n 50 --no-pager     # systemd 形态的日志
$ sudo tail -f /var/log/meta.sr.ht.log               # unit 未配 journal 时看应用日志
$ sudo tail -f /var/log/nginx/error.log              # clone 链路错误在这里

监控点提示：两个 Go API 启动时会随机开三个附加端口，日志里可见（实测）：

2026/10/28 02:05:31 Running on [:5100]
2026/10/28 02:05:31 Prometheus listening on [::]:34085
2026/10/28 02:05:31 pprof listening on 127.0.0.1:41717

Prometheus 指标端口是随机分配的，接入监控前先固定（core-go 支持通过环境/配置指定）或用服务发现读取日志；pprof 端口仅监听本机回环，注意不要在公网暴露。

二、用户管理：meta.sr.ht-manageuser 全用法

2.1 命令签名

$ /opt/venv/bin/meta.sr.ht-manageuser
Usage:
    meta.sr.ht-manageuser [-fmPps] [-e <EMAIL>] [-t <USER_TYPE>] <USERNAME>

Options:
    -e <EMAIL>      set user email
    -f              perform action even if using different authentication method
    -m              modify existing user
    -P              clear password
    -p              set password (default if creating a new user)
    -s              read initial password from stdin (only effective with -p)
    -t <USER_TYPE>  USER_TYPE ∈ PENDING | USER | ADMIN | SUSPENDED

2.2 高频操作（全部实测）

# 修改密码（无终端环境必须 -s 从 stdin 读，否则 EOFError）
$ echo 'new-pass-123' | sudo /opt/venv/bin/meta.sr.ht-manageuser -m -p -s srhtadmin

# 提权为管理员
$ echo 'q1w2e3r4' | sudo /opt/venv/bin/meta.sr.ht-manageuser -m -p -s -t ADMIN srhtadmin

# 建号（关闭公开注册场景下管理员代建）
$ echo 'init-pass' | sudo /opt/venv/bin/meta.sr.ht-manageuser -p -s -t USER alice

# 封禁 / 解封
$ sudo /opt/venv/bin/meta.sr.ht-manageuser -m -t SUSPENDED alice
$ sudo /opt/venv/bin/meta.sr.ht-manageuser -m -t USER alice

用户状态核对（user 表名是小写保留字，查询要加引号）：

$ PGPASSWORD=q1w2e3r4 psql -h 127.0.0.1 -U srht -d meta \
    -tc 'SELECT username, email, user_type FROM "user"'
 srhtadmin | admin@srht.local | ADMIN

注册类排障速记：admin/root/api 等是上游硬编码保留名（metasrht/blacklist.py 的 username_blacklist），注册报 This username is not available 属正常拦截；无 SMTP 时注册成功的账号停在 PENDING，需用上面命令转 USER/ADMIN。

三、数据库运维

3.1 库表概览

$ PGPASSWORD=q1w2e3r4 psql -h 127.0.0.1 -U srht -d meta -tc \
    "SELECT count(*) FROM information_schema.tables WHERE table_schema='public'"
     26
$ PGPASSWORD=q1w2e3r4 psql -h 127.0.0.1 -U srht -d git -tc \
    "SELECT count(*) FROM information_schema.tables WHERE table_schema='public'"
     10

（meta 26 表 / git 10 表为 0.88.9 / 0.102.8 的实测基线，升级后可复跑对比。）

3.2 备份与恢复

# 逻辑备份（两库一卡车载）
$ sudo -u postgres pg_dump meta  | gzip > /backup/meta-$(date +%F).sql.gz
$ sudo -u postgres pg_dump git   | gzip > /backup/git-$(date +%F).sql.gz

# 恢复到空库
$ sudo -u postgres psql -c 'CREATE DATABASE meta2 OWNER srht'
$ gunzip -c /backup/meta-2026-10-28.sql.gz | sudo -u postgres psql meta2

重要：git 库只存元数据（仓库列表、权限、redirect），仓库内容在文件系统 /var/lib/git/。完整备份必须"数据库 + 仓库目录"成对：

$ sudo tar czf /backup/repos-$(date +%F).tar.gz /var/lib/git/

单个仓库的便携备份用裸仓库协议自带能力：

$ sudo git -C /var/lib/git/~srhtadmin/demo-repo bundle create /backup/demo-repo.bundle --all

恢复即 git clone demo-repo.bundle 或解包到原路径后核对 git 库中 repository 表的 path 记录。

3.3 一致性巡检

# 仓库文件系统 vs git 元数据库逐仓核对（裸仓库 fsck）
$ sudo find /var/lib/git -mindepth 3 -maxdepth 3 -type d \
    -exec git -C {}/ fsck --no-dangling \;

（预期结果标注：最小集且无推送流量时输出为空；fsck 有 damaged 输出时优先考虑备份恢复而非在线修复。）

四、版本升级流程（0.88.9 → 下一版）

Sourcehut 各服务独立发版，升级以"服务对"为单位（meta 对、git 对）。以 git.sr.ht 为例：

预检：读新 tag 的 config.example.ini，diff 出新增/改名参数（本系列升级实测口径：0.101.x → 0.102.x 无配置破坏性变更）。
备份先行：3.2 节两件套（数据库 + 仓库目录）。
下载与 Python 侧：

$ cd /opt/srht && curl -LO https://git.sr.ht/~sircmpwn/git.sr.ht/archive/0.102.8.tar.gz
$ tar xzf 0.102.8.tar.gz && cd git.sr.ht-0.102.8
$ ariadne-codegen                                  # 生成 GraphQL 客户端（新包必做）
$ /opt/venv/bin/pip install ./git.sr.ht-0.102.8    # venv 内升级

静态资源：按安装篇 5.2 重编译 SCSS（样式有变时页面样式丢失的最常见原因就是只升包没升资源）。
Go 侧：go generate ./loaders ./graph + go build ./cmd/api，update-hook/http-clone 一并重编。
数据库迁移：官方工具 sourcehut-migrate git.sr.ht upgrade（无该工具时核对新 tarball 的 migrations/*.sql 是否晚于当前版本，逐个以 psql 应用；schema.sql 已含最新结构，全新库直接导入即可）。
滚动重启：先 api 后 web（git.sr.ht-api → git.sr.ht），探活矩阵过一遍，页面回归建仓/克隆。
meta 对同理，注意 meta.sr.ht-daily（每日任务：账单、欢迎邮件、密钥到期提醒）的 cron 也要指向新版路径。

五、故障排查手册

5.1 按症状定位

Web 502/连接拒绝：

$ systemctl status git.sr.ht --no-pager        # 进程死了？
$ ps -eo pid,cmd | grep gitsrht | grep -v grep

常见根因与处置：

worker 启动即退（日志见 Worker failed to boot）：Python 侧导入错误，多为 venv 包不完整或缺依赖，对照安装篇 3.3/3.4 补齐；--chdir 留在源码目录也会触发，务必换干净目录。
500 且日志见 Exception on /xxx：把堆栈最后一行 KeyError/ModuleNotFoundError 对照配置篇速查表第 9 条处理。

登录后跨服务仍未登录：cookie 域问题，见配置篇速查表第 5 条——用域名访问，核对 global-domain。

建仓失败：优先查两条配置——post-update-script 是否指向 update-hook 二进制（速查表第 3 条）、git.sr.ht 是否配了 api-origin（第 4 条）。

HTTP clone 404/500：404 先确认仓库可见性（PRIVATE 会被 clone 网关拒绝）与路径 ~user/repo 拼写；500 看 /var/log/nginx/error.log，dubious ownership 用速查表第 8 条修。

API 401 想确认功能：用带内部认证的调用（服务间走法）或直接从 Web 层触发一次对应动作（如建仓），观察 API 日志。

5.2 日志位置速查

通道	位置
Web 层应用日志	unit 定义文件里指向的路径（本文 `/var/log/*.sr.ht.log`）
Go API 日志	同上（`*-api.log`），含 Prometheus/pprof 端口声明
nginx 访问/错误	`/var/log/nginx/access.log`、`error.log`
PostgreSQL	`/var/log/postgresql/postgresql-14-main.log`
systemd journal	`journalctl -u <unit>`

六、日常巡检清单

探活矩阵四项全绿（Web 200 ×2、API 401 ×2）
systemctl --failed 无失败单元
磁盘余量（df -h /var/lib/git）：裸仓库只增不减，git 库随仓库数线性增长
Redis 内存与连接（redis-cli info memory | grep used_memory_human）
昨日 nginx error.log 无新增 5xx 模式
数据库备份任务昨日成功（文件存在且可 gunzip -t）
仓库目录备份任务昨日成功
随机抽查一个仓库 fsck / 页面可打开

参考资料

meta.sr.ht-manageuser 帮助（随版本安装，上文为 0.88.9 实测原文）
官方自托管文档：https://man.sr.ht/pages/install.md
系列篇目：《Sourcehut 介绍与选型指南》《Sourcehut 0.88.9 + git.sr.ht 0.102.8 Ubuntu 22.04 安装指南》《Sourcehut 配置参数详解》