10分钟搭建私有Git服务器：Soft Serve实战

做后端开发和运维时，团队内部经常有工具脚本、配置模板、实验性项目需要托管。推到GitHub公开仓库不合适，搭GitLab又消耗大量内存，Gitea虽然轻量但仍需安装数据库、配置Web界面。很多时候我只想要一条命令搞定、纯命令行交互、SSH就能管理的那种方案。

Soft Serve 正好满足这个需求。这是 charmbracelet 团队（Bubble Tea 命令行 UI 库的创作者）用 Go 编写的自托管 Git 服务器。一个二进制文件跑起来就行，通过 SSH 进行全部管理，自带 TUI 终端界面可以直接浏览仓库。目前近 7000 星，社区活跃度高。

这篇文章带你从零开始在一台 Linux 服务器上部署 Soft Serve，完成用户创建、权限管理、仓库推送全流程操作。

前置条件

一台 Linux/macOS 服务器（推荐 Ubuntu 20.04+ 或 CentOS 8+）用于运行服务端
本地开发机已安装 git，且已生成 SSH 密钥（推荐 Ed25519）
服务端已安装 git
了解基本的 SSH 操作和 Git 远程仓库概念

为什么推荐 Ed25519 密钥？ Soft Serve 依赖 Go 的 x/crypto/ssh 库，对新型 RSA 密钥支持不完善。如果你是新的 RSA 格式密钥，SSH 认证可能失败。检查密钥类型：
bash 复制代码
ssh-keygen -l -f ~/.ssh/id_ed25519.pub

快速上手：四步跑起来

第一步：安装 Soft Serve

Soft Serve 是单个二进制文件 soft，安装方式多样。服务器上推荐用 Go 安装（最通用）：

bash 复制代码

# 确保 Go 已安装（1.19+）
go install github.com/charmbracelet/soft-serve/cmd/soft@latest

# 安装后 binary 在 $GOPATH/bin/soft，移到 PATH 中
sudo mv ~/go/bin/soft /usr/local/bin/

macOS 或习惯 Homebrew 的 Linux 用户更简单：

bash 复制代码

brew install charmbracelet/tap/soft-serve

Debian/Ubuntu 用户也可以用 apt：

bash 复制代码

sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://repo.charm.sh/apt/gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/charm.gpg
echo "deb [signed-by=/etc/apt/keyrings/charm.gpg] https://repo.charm.sh/apt/ * *" | sudo tee /etc/apt/sources.list.d/charm.list
sudo apt update && sudo apt install soft-serve

第二步：首次启动与管理员配置

这一步是核心。Soft Serve 首次启动时，必须通过环境变量 SOFT_SERVE_INITIAL_ADMIN_KEYS 指定管理员的 SSH 公钥，系统才能知道谁是管理员。

在本地机器上查看公钥：

bash 复制代码

cat ~/.ssh/id_ed25519.pub

复制整行输出（形如 ssh-ed25519 AAAA... user@host），回到服务器执行：

bash 复制代码

SOFT_SERVE_INITIAL_ADMIN_KEYS="把上面的SSH公钥粘贴到这里" soft serve

启动后会看到类似日志：

复制代码

INFO Starting Soft Serve server...
INFO SSH listening on :23231
INFO HTTP listening on :23232

服务已经运行。默认情况下，Soft Serve 会把所有数据（仓库、密钥、数据库）存在当前目录的 data/ 文件夹下。 更换位置可用环境变量 SOFT_SERVE_DATA_PATH 指定。

为什么首次启动必须设管理员公钥？ Soft Serve 没有 Web 注册页面，一切权限管理靠 SSH。首次启动指定的公钥会被创建为 admin 用户，拥有全部权限。忘记设置后续只能手动改配置文件找回管理员权限。

第三步：配置 SSH 快捷访问

每次连接 Soft Serve 都要敲 ssh localhost -p 23231 -i ~/.ssh/id_ed25519 -o IdentitiesOnly=yes，又长又容易忘。把它加到 SSH 配置文件里。

编辑本地机器 的 ~/.ssh/config：

conf 复制代码

Host soft
  HostName 你的服务器IP或域名
  Port 23231
  IdentityFile ~/.ssh/id_ed25519
  IdentitiesOnly yes

之后直接用 ssh soft 就能访问。git 客户端也会读取这个配置，后续 git clone ssh://soft/repo-name 可直接复用。

第四步：验证连接

bash 复制代码

ssh soft help

看到 user、repo、settings 等子命令列表，说明服务端部署完成。

实战：搭建团队代码仓库

假设团队有三个人：你（管理员）、Beatrice（开发）、Frankie（开发）。需要创建私有仓库 backend-utils 供三人协作。

1. 创建用户

作为管理员，通过 ssh soft 连接后创建团队成员：

bash 复制代码

# 创建用户（默认只读权限）
ssh soft user create beatrice
ssh soft user create frankie

# 给 Beatrice 添加 SSH 公钥
ssh soft user add-pubkey beatrice "ssh-ed25519 AAAA... beatrice@laptop"

# 创建 Frankie 时直接带公钥
ssh soft user create frankie '-k "ssh-ed25519 AAAA... frankie@desktop"'

权限默认值： 新建用户默认只能读公共仓库。要获得写权限，需被添加为仓库协作者。

2. 创建仓库并设置权限

bash 复制代码

# 创建仓库（-p 表示私有）
ssh soft repo create backend-utils -p \
  -d "团队内部工具库和公共组件" \
  -n "Backend Utils"

仓库创建后，管理员自动拥有全部权限。把 Beatrice 和 Frankie 添加为协作者：

bash 复制代码

# 添加读写权限的协作者
ssh soft repo collab add backend-utils beatrice read-write
ssh soft repo collab add backend-utils frankie read-write

# 查看协作者列表
ssh soft repo collab list backend-utils

3. 推送代码到仓库

任何被授权的机器上，操作方式与 GitHub 一致：

bash 复制代码

# 克隆
git clone ssh://soft/backend-utils

cd backend-utils

# 正常开发、提交
echo "# Backend Utils" > README.md
git add .
git commit -m "init"
git push origin main

不想先 clone 再推送，也可以直接添加 remote：

bash 复制代码

git remote add origin ssh://soft/backend-utils
git push origin main

Soft Serve 有个贴心设计：如果远程仓库不存在，第一次 push 时会自动创建 。所以可以跳过 repo create 步骤直接 git push。

4. 用 TUI 浏览仓库

bash 复制代码

ssh soft

进入漂亮的终端界面，列出所有有权限访问的仓库。方向键选择后可直接浏览目录结构、查看文件内容（带语法高亮和行号）、复制 clone 命令等。在服务器上做代码 review 或排查问题非常方便。

常见问题与踩坑提醒

1. SSH RSA 密钥认证失败

ssh soft 提示权限拒绝但公钥已正确配置，大概率是 SSH 密钥格式问题。Soft Serve 暂不支持 RSA SHA-256 格式密钥。改用 Ed25519 密钥（推荐），或使用旧版 SHA-1 格式的 RSA 密钥。

2. 匿名访问太开放

默认配置下 anon-access 为 read-only，任何人都能 git clone 公共仓库。内网部署无所谓，开放到公网建议调整：

bash 复制代码

# 关闭匿名访问
ssh soft settings anon-access no-access

# 或限制为只允许有密钥的用户
ssh soft settings allow-keyless false

3. 生产环境怎么持久运行？

soft serve 默认是前台进程，关掉终端就停了。建议使用 systemd 管理，官方提供了 systemd 配置模板，装完直接用 systemctl start soft-serve 即可。

4. 想用 PostgreSQL 代替 SQLite？

默认数据库是 SQLite，小团队够用。有现成 PostgreSQL 可以这样切换：

bash 复制代码

# 建库
psql -U postgres -c 'CREATE DATABASE soft_serve'

# 启动时指定
SOFT_SERVE_DB_DRIVER=postgres \
SOFT_SERVE_DB_DATA_SOURCE="postgres://postgres:password@localhost:5432/soft_serve?sslmode=disable" \
soft serve

5. Webhook 集成 CI/CD

Soft Serve 支持仓库级 webhook，事件包括 push、collaborators、branch_tag_create。push 后可触发 Jenkins/GitHub Actions 等流水线：

bash 复制代码

ssh soft repo webhook create backend-utils \
  --url "https://jenkins.example.com/webhook/soft-serve" \
  --events push

总结

今天用 Soft Serve 完成了完整的搭建链：安装 → 配置管理员公钥 → SSH 便捷连接 → 创建用户和仓库 → 配置权限 → 推送代码 → TUI 浏览。整个过程没有碰过浏览器、没有装数据库、没有写 Nginx 配置，一个二进制文件配合 SSH 密钥就搞定。

下一步建议：

研究 Soft Serve 的 git hooks 功能，在仓库目录下加 hooks/post-receive 脚本实现推送自动部署
试试 repo import --mirror 从 GitHub 镜像仓库到本地做离线备份
有 Docker 环境可以看看官方 docker.md，容器化部署更省心

Soft Serve 不适合替代 GitHub（没有 PR review、没有 Issue 跟踪），但非常适合团队内部代码托管、边缘节点部署、私有实验项目协作用途。如果需求就是「能 push/pull、能管理权限、能 webhook 触发」，这就是最佳选择。