charmcli/soft-serve

Soft Serve

镜像概述和主要用途

Soft Serve是一个轻量级自托管命令行Git服务器，旨在提供简单高效的私有Git仓库管理解决方案。它通过SSH提供交互式终端用户界面（TUI），支持多协议仓库克隆，并允许通过SSH命令直接管理仓库、用户权限和服务器配置。适用于个人开发者、小团队或需要独立Git服务的场景，无需依赖第三方平台即可搭建功能完善的私有Git服务器。

核心功能和特性

• 交互式TUI：通过SSH访问的终端界面，支持浏览仓库、查看文件/提交历史、复制克隆命令
• 多协议支持：兼容SSH、HTTP和Git协议克隆仓库
• SSH命令管理：直接通过SSH命令创建、删除、重命名仓库及管理用户权限
• 按需创建仓库：支持通过git push或SSH命令即时创建新仓库
• 灵活访问控制：支持***访问（只读/禁止）和四级用户权限（无访问、只读、读写、管理员）
• 私有仓库：可设置仓库为私有，仅限授权协作者访问
• 文件浏览功能：通过SSH命令查看仓库文件树、文件内容，支持语法高亮和行号显示
• Git钩子支持：集成Git服务器端钩子（pre-receive、update等），支持自定义工作流

使用场景和适用范围

• 个人私有Git服务：开发者搭建个人代码仓库，完全掌控数据和访问权限
• 小团队协作：团队内部共享代码，无需依赖GitHub/GitLab等第三方服务
• 嵌入式/边缘环境：轻量级部署，适合资源有限的服务器或开发环境
• 演示/测试环境：快速搭建临时Git服务，用于项目演示或测试

详细使用方法和配置说明

Docker部署示例

基础部署（docker run）

bash
# 默认配置启动
docker run -d -p 23231:23231 -p 23232:23232 -p 9418:9418 --name soft-serve charmcli/soft-serve

# 持久化数据存储
docker run -d -p 23231:23231 -p 23232:23232 -p 9418:9418 \
  -v /path/to/soft-serve-data:/data \
  -e SOFT_SERVE_DATA_PATH=/data \
  --name soft-serve charmcli/soft-serve

# 指定初始管理员密钥
docker run -d -p 23231:23231 -p 23232:23232 -p 9418:9418 \
  -e SOFT_SERVE_INITIAL_ADMIN_KEYS="ssh-rsa AAAAB3NzaC1yc2... ssh-ed25519 AAAA..." \
  --name soft-serve charmcli/soft-serve

docker-compose配置

yaml
version: '3'
services:
  soft-serve:
    image: charmcli/soft-serve
    ports:
      - "23231:23231"  # SSH端口
      - "23232:23232"  # HTTP端口
      - "9418:9418"    # Git协议端口
    volumes:
      - ./soft-serve-data:/data  # 持久化数据
    environment:
      - SOFT_SERVE_NAME="My Git Server"  # 服务器名称
      - SOFT_SERVE_DATA_PATH=/data       # 数据存储路径
      - SOFT_SERVE_SSH_LISTEN_ADDR=:23231 # SSH监听地址
      - SOFT_SERVE_HTTP_PUBLIC_URL=http://localhost:23232 # HTTP公共URL
      - SOFT_SERVE_INITIAL_ADMIN_KEYS="ssh-rsa AAAAB3NzaC1yc2..." # 管理员公钥
    restart: unless-stopped

服务器配置

初始设置

首次启动时，Soft Serve会在数据目录创建仓库存储、SSH密钥和配置文件。核心配置项可通过环境变量或config.yaml（位于数据目录）调整，常用环境变量：

• SOFT_SERVE_NAME：服务器名称（显示在TUI中）
• SOFT_SERVE_SSH_LISTEN_ADDR：SSH服务监听地址（默认:23231）
• SOFT_SERVE_HTTP_LISTEN_ADDR：HTTP服务监听地址（默认:23232）
• SOFT_SERVE_ANON_ACCESS：***用户访问级别（默认read-only，可选no-access/read-write/admin-access）
• SOFT_SERVE_ALLOW_KEYLESS：是否允许无密钥访问（默认true，影响HTTP/Git协议）

管理员配置

通过SOFT_SERVE_INITIAL_ADMIN_KEYS环境变量设置初始管理员SSH公钥，多个密钥用空格分隔。管理员拥有服务器完全控制权，可管理所有用户和仓库。

基本使用方法

访问TUI界面

通过SSH直接连接服务器即可打开交互式界面：

bash
ssh <服务器IP> -p 23231

连接指定仓库：

bash
ssh <服务器IP> -p 23231 -t <仓库名>

克隆仓库

支持多种协议克隆：

bash
# SSH协议
git clone ssh://<服务器IP>:23231/<仓库名>

# HTTP协议
git clone http://<服务器IP>:23232/<仓库名>

# Git协议
git clone git://<服务器IP>:9418/<仓库名>

SSH配置简化

在~/.ssh/config中添加配置简化访问：

conf
Host soft-serve
  HostName <服务器IP>
  Port 23231
  IdentityFile ~/.ssh/id_ed25519  # 用于认证的私钥

之后可使用简化命令：

bash
ssh soft-serve          # 访问TUI
git clone ssh://soft-serve/<仓库名>  # 克隆仓库

仓库管理

创建仓库

bash
# 基本创建
ssh soft-serve repo create <仓库名>

# 创建带描述和项目名称的仓库
ssh soft-serve repo create <仓库名> -d "项目描述" -n "项目名称"

# 创建私有仓库
ssh soft-serve repo create <仓库名> -p

查看和操作仓库内容

bash
# 查看仓库文件树
ssh soft-serve repo tree <仓库名> <路径>

# 查看文件内容（带语法高亮和行号）
ssh soft-serve repo blob <仓库名> <文件路径> -c -l

# 获取仓库信息
ssh soft-serve repo info <仓库名>

修改和删除仓库

bash
# 重命名仓库
ssh soft-serve repo rename <旧名称> <新名称>

# 设置仓库为私有
ssh soft-serve repo private <仓库名> true

# 删除仓库
ssh soft-serve repo delete <仓库名>

用户和权限管理

用户管理

bash
# 创建用户
ssh soft-serve user create <用户名>

# 添加用户SSH公钥
ssh soft-serve user add-pubkey <用户名> "ssh-ed25519 AAAA..."

仓库协作权限

bash
# 添加协作者（读写权限）
ssh soft-serve repo collab add <仓库名> <用户名>

# 移除协作者
ssh soft-serve repo collab remove <仓库名> <用户名>

# 列出协作者
ssh soft-serve repo collab list <仓库名>

Git钩子配置

Soft Serve支持Git服务器端钩子，全局钩子位于数据目录的hooks文件夹，仓库特定钩子位于仓库的hooks目录。例如创建全局update钩子：

bash
# 在数据目录创建钩子文件
cat > /path/to/data/hooks/update << 'EOF'
#!/bin/sh
refname="$1"
oldrev="$2"
newrev="$3"
echo "推送事件：$refname $oldrev $newrev"
EOF
chmod +x /path/to/data/hooks/update

注意事项

• 密钥兼容性：暂不支持SHA-256签名的RSA密钥，建议使用Ed25519或ECDSA密钥
• 终端支持：TUI的复制功能依赖终端对OSC52协议的支持（如iTerm2、Alacritty等）
• 数据持久化：确保数据目录（SOFT_SERVE_DATA_PATH）通过Docker卷持久化，避免容器重建导致数据丢失
• ***访问控制：修改anon-access和allow-keyless设置时需谨慎，避免未授权访问私有数据