charmbracelet/soft-serve

# 软服务

一款美味、可自托管的命令行 Git 服务器。🍦 - 通过 SSH 可用的易于导航的 TUI - 通过 SSH、HTTP 或 Git 协议克隆仓库 - 支持使用 HTTP 和 SSH 后端进行 Git LFS - 使用 SSH 管理仓库 - 使用 SSH 或 `git push` 需求创建仓库 - 使用可 SSH 访问的 UI 浏览仓库、文件和提交 - 使用 SSH 打印文件，可选语法高亮和行号 - 易于访问控制 - 使用公钥进行 SSH 认证 - 允许/禁止匿名访问 - 使用 SSH 公钥添加协作者 - 仓库可以是公开的或私有的 - 用户访问令牌 ## 我在哪里可以看到它？ 只需运行 `ssh git.charm.sh` 即可查看示例。您还可以尝试以下命令： ``` # 跳转到 TUI 中的仓库 ssh git.charm.sh -t soft-serve # 打印出仓库的目录树 ssh git.charm.sh repo tree soft-serve # 打印特定文件 ssh git.charm.sh repo blob soft-serve cmd/soft/main.go # 打印带语法高亮和行号的文件 ssh git.charm.sh repo blob soft-serve cmd/soft/main.go -c -l ``` 或者，您可以使用 Soft Serve 使用 `soft browse [目录]` 或在 Git 仓库中运行 `soft` 来浏览本地仓库。 ## 安装 Soft Serve 是一个名为 `soft` 的单个二进制文件。您可以从软件包管理器中获取它： ``` # macOS 或 Linux brew install charmbracelet/tap/soft-serve # Windows（带 Winget） winget install charmbracelet.soft-serve # Arch Linux pacman -S soft-serve # Nix nix-env -iA nixpkgs.soft-serve # Debian/Ubuntu 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 # Fedora/RHEL echo '[charm] name=Charm baseurl=https://repo.charm.sh/yum/ enabled=1 gpgcheck=1 gpgkey=https://repo.charm.sh/yum/gpg.key' | sudo tee /etc/yum.repos.d/charm.repo sudo yum install soft-serve ``` 您也可以从 [发布页面][releases] 下载二进制文件。软件包以 Alpine、Debian 和 RPM 格式提供。二进制文件适用于 Linux、macOS 和 Windows。 或者只需使用 `go` 安装： ``` go install github.com/charmbracelet/soft-serve/cmd/soft@latest ``` 一个 [Docker 镜像][docker] 也可用。 ## 设置服务器 确保已安装 `git`，然后运行 `soft serve`。就这样。 这将创建一个 `data` 目录，用于存储所有仓库、ssh 密钥和数据库。 默认情况下，程序配置存储在 `data` 目录中。但是，您可以使用 `SOFT_SERVE_CONFIG_LOCATION` 设置自定义路径到配置文件来覆盖它。如果 `SOFT_SERVE_CONFIG_LOCATION` 指向配置文件，则默认位置在 `data` 目录内用于生成默认配置。 要更改默认数据路径，请使用 `SOFT_SERVE_DATA_PATH` 环境变量。 ``` SOFT_SERVE_DATA_PATH=/var/lib/soft-serve soft serve ``` 当您第一次运行 Soft Serve 时，请确保您已设置 `SOFT_SERVE_INITIAL_ADMIN_KEYS` 环境变量为您的 ssh 授权密钥。添加到此变量的任何密钥都将被视为具有完整权限的管理员。 使用此环境变量，Soft Serve 将创建一个新的 `admin` 用户，该用户具有完整权限。您可以在以后重命名和更改用户设置。 有关如何使用 Systemd 运行 Soft Serve 作为服务的说明，请参阅 [Systemd][systemd]。我们 Apt/Yum 仓库中的 Soft Serve 软件包附带 Systemd 服务单元。 ### 服务器配置 一旦您第一次启动服务器，设置将位于您数据目录下的 `config.yaml` 中。默认的 `config.yaml` 是自我解释的，看起来像这样： ``` # Soft Serve 服务器配置 # 服务器的名称。 # 这是将在 UI 中显示的名称。 name: "Soft Serve" # 要使用的日志格式。有效值是 "json"、"logfmt" 和 "text"。 log_format: "text" # SSH 服务器配置。 ssh: # The address on which the SSH server will listen. listen_addr: ":23231" # The public URL of the SSH server. # This is the address that will be used to clone repositories. public_url: "ssh://localhost:23231" # The path to the SSH server's private key. key_path: "ssh/soft_serve_host" # The path to the SSH server's client private key. # This key will be used to authenticate the server to make git requests to # ssh remotes. client_key_path: "ssh/soft_serve_client" # The maximum number of seconds a connection can take. # A value of 0 means no timeout. max_timeout: 0 # The number of seconds a connection can be idle before it is closed. idle_timeout: 120 # Git daemon 配置。 git: # The address on which the Git daemon will listen. listen_addr: ":9418" # The maximum number of seconds a connection can take. # A value of 0 means no timeout. max_timeout: 0 # The number of seconds a connection can be idle before it is closed. idle_timeout: 3 # The maximum number of concurrent connections. max_connections: 32 # HTTP 服务器配置。 http: # The address on which the HTTP server will listen. listen_addr: ":23232" # The path to the TLS private key. tls_key_path: "" # The path to the TLS certificate. tls_cert_path: "" # The public URL of the HTTP server. # This is the address that will be used to clone repositories. # Make sure to use https:// if you are using TLS. public_url: "http://localhost:23232" # The cross-origin request security options cors: # The allowed cross-origin headers allowed_headers: - "Accept" - "Accept-Language" - "Content-Language" - "Content-Type" - "Origin" - "X-Requested-With" - "User-Agent" - "Authorization" - "Access-Control-Request-Method" - "Access-Control-Allow-Origin" # The allowed cross-origin URLs allowed_origins: - "http://localhost:23232" # always allowed # - "https://example.com" # The allowed cross-origin methods allowed_methods: - "GET" - "HEAD" - "POST" - "PUT" - "OPTIONS" # 数据库配置。 db: # The database driver to use. # Valid values are "sqlite" and "postgres". driver: "sqlite" # The database data source name. # This is driver specific and can be a file path or connection string. # Make sure foreign key support is enabled when using SQLite. data_source: "soft-serve.db?_pragma=busy_timeout(5000)&_pragma=foreign_keys(1)" # Git LFS 配置。 lfs: # Enable Git LFS. enabled: true # Enable Git SSH transfer. ssh_enabled: false # Cron 作业配置 jobs: mirror_pull: "@every 10m" # 统计服务器配置。 stats: # The address on which the stats server will listen. listen_addr: ":23233" # 额外的管理员密钥。 #initial_admin_keys: # - "ssh-rsa AAAAB3NzaC1yc2..." ``` 您也可以使用环境变量来覆盖这些设置。所有服务器设置环境变量都以 `SOFT_SERVE_` 开头，后面跟设置名称，全部大写。以下是一些示例： - `SOFT_SERVE_NAME`：将在 TUI 中显示的服务器名称 - `SOFT_SERVE_SSH_LISTEN_ADDR`：SSH 监听地址 - `SOFT_SERVE_SSH_KEY_PATH`：SSH 主机密钥对路径 - `SOFT_SERVE_HTTP_LISTEN_ADDR`：HTTP 监听地址 - `SOFT_SERVE_HTTP_PUBLIC_URL`：用于克隆的 HTTP 公共 URL - `SOFT_SERVE_GIT_MAX_CONNECTIONS`：到 git 守护进程的并发连接数 #### 数据库配置 Soft Serve 支持 SQLite 和 Postgres 作为其数据库。与其他所有 Soft Serve 设置一样，您可以使用 `config.yaml` 或环境变量来更改数据库 _driver_ 和 _data source_。默认配置使用 SQLite 作为默认数据库驱动程序。 要使用 Postgres 作为数据库，首先创建一个 Soft Serve 数据库： ``` psql -h -p -U -c 'CREATE DATABASE soft_serve' ``` 然后设置数据库 _data source_ 以指向您的 Postgres 数据库。例如，如果您在本地运行 Postgres，使用默认用户 `postgres` 和数据库名称 `soft_serve`，则您的配置文件或环境变量中将具有以下配置： ``` db: driver: "postgres" data_source: "postgres://postgres@localhost:5432/soft_serve?sslmode=disable" ``` 环境变量等效： ``` SOFT_SERVE_DB_DRIVER=postgres \ SOFT_SERVE_DB_DATA_SOURCE="postgres://postgres@localhost:5432/soft_serve?sslmode=disable" \ soft serve ``` 您可以在 _data source_ url 中指定数据库连接密码。例如，`postgres://myuser:dbpass@localhost:5432/my_soft_serve_db`。 #### LFS 配置 Soft Serve 默认支持 Git LFS [HTTP](https://github.com/git-lfs/git-lfs/blob/main/docs/api/README.md) 和 [SSH](https://github.com/git-lfs/git-lfs/blob/main/docs/proposals/ssh_adapter.md) 协议，无需进行任何额外设置。 使用 `lfs` 配置部分来自定义您的 Git LFS 服务器。 ## 服务器访问 Soft Serve 在核心上管理您的服务器身份验证和授权。身份验证验证用户的身份，而授权确定他们对仓库的访问权限。 要管理服务器用户、访问和仓库，您可以使用 SSH 命令行界面。 尝试 `ssh localhost -i ~/.ssh/id_ed25519 -o IdentitiesOnly=yes -p 23231 help` 获取更多信息。请确保 您在这里使用您的密钥。 为了方便使用，您无需每次都指定密钥、端口和主机名来 SSH 连接到 Soft Serve，您可以将自己的 Soft Serve 实例条目添加到您的 SSH 配置中。例如，要使用 `ssh soft` 而不是键入 `ssh localhost -i ~/.ssh/id_ed25519 -o IdentitiesOnly=yes -p 23231`，我们可以在我们的 SSH 配置文件 `~/.ssh/config` 中定义一个 `soft` 条目。 ``` Host soft HostName localhost Port 23231 IdentityFile ~/.ssh/id_ed25519 IdentitiesOnly yes ``` 现在，我们可以使用 `ssh soft` 连接到 Soft Serve。由于 `git` 也知道此配置，您可以使用 `soft` 作为克隆命令的主机名。 ``` git clone ssh://soft/dotfiles # 进行更改 # 添加并提交 git push origin main ``` ### 身份验证 需要身份验证的一切都使用 SSH 完成。确保您已在您的 `~/.ssh/config` 文件中添加了您的 Soft Serve 实例条目。 默认情况下，Soft Serve 给匿名连接到上述任何协议的任何仓库只提供只读权限。这由两个设置 `anon-access` 和 `allow-keyless` 控制。 - `anon-access`：定义匿名用户的访问级别。可用选项是 `no-access`、`read-only`、`read-write` 和 `admin-access`。默认值为 `read-only`。 - `allow-keyless`：是否允许不使用密钥的连接通过。将此设置为 `false` 将禁用 SSH、HTTP 和 Git 协议连接的键盘交互式访问。默认值为 `true`。 ``` $ ssh -p 23231 localhost settings Manage server settings Usage: ssh -p 23231 localhost settings [command] Available Commands: allow-keyless Set or get allow keyless access to repositories anon-access Set or get the default access level for anonymous users Flags: -h, --help help for settings Use "ssh -p 23231 localhost settings [command] --help" for more information about a command. ``` 当 `allow-keyless` 禁用时，不使用 SSH 公钥身份验证的连接将遭到拒绝。这意味着通过 HTTP(s) 或 git:// 克隆仓库将遭到拒绝。 同时，`anon-access` 控制使用 SSH 公钥身份验证但未注册的用户授予的访问级别。此设置的默认值是 `read-only`。这将授予使用 SSH 公钥身份验证的匿名连接对公共仓库的 `read-only` 访问权限。 `anon-access` 也与 `allow-keyless` 结合使用，以确定 HTTP(s) 和 git:// 克隆请求的访问级别。 #### SSH Soft Serve 不允许用户有重复的 SSH 公钥。公钥只能与一个用户关联。这使得 SSH 身份验证简单直接，将您的公钥添加到 Soft Serve 用户中即可访问 Soft Serve。 #### HTTP 您可以通过 SSH 命令行界面生成用户访问令牌。访问令牌可以有一个可选的过期日期。使用您的访问令牌作为基本身份验证用户通过 HTTP 访问您的 Soft Serve 仓库。 ``` # 创建用户令牌 ssh -p 23231 localhost token create 'my new token' ss_1234abc56789012345678901234de246d798fghi # 或带有过期日期 ssh -p 23231 localhost token create --expires-in 1y 'my other token' ss_98fghi1234abc56789012345678901234de246d7 ``` 现在您可以访问需要 `read-write` 访问的仓库。 ``` git clone http://ss_98fghi1234abc56789012345678901234de246d7@localhost:23232/my-private-repo.git my-private-repo # 进行更改并推送 ``` ### 授权 Soft Serve 提供简单的访问控制。有四个访问级别：无访问、只读、读写和管理员访问。 `admin-access` 对服务器有完全控制权，可以更改用户和仓库。 `read-write` 访问对仓库有完全控制权。 `read-only` 可以读取公共仓库。 `no-access` 拒绝对所有仓库的访问。 ## 用户管理 管理员可以使用 `user` 命令管理用户及其密钥。一旦创建用户并获得对服务器的访问权限，他们就可以管理自己的密钥和设置。 要创建新用户，只需使用 `user create`： ``` # 创建新用户 ssh -p 23231 localhost user create beatrice # 添加用户密钥 ssh -p 23231 localhost user add-pubkey beatrice ssh-rsa AAAAB3Nz... ssh -p 23231 localhost user add-pubkey beatrice ssh-ed25519 AAAA... # 使用公钥创建另一个用户 ssh -p 23231 localhost user create frankie '-k "ssh-ed25519 AAAATzN..."' # 需要帮助？ ssh -p 23231 localhost user help ``` 一旦创建用户，他们就会获得对公共仓库的 `read-only` 访问权限。他们还可以在服务器上创建新的仓库。 用户可以使用 `pubkey` 命令管理他们的密钥： ``` # 列出用户密钥 ssh -p 23231 localhost pubkey list # 添加密钥 ssh -p 23231 localhost pubkey add ssh-ed25519 AAAA... # 想更改用户名吗？ ssh -p 23231 localhost set-username yolo # 显示用户信息 ssh -p 23231 localhost info ``` ## 仓库 您可以使用 `repo` 命令管理仓库。 ``` # 运行仓库帮助 $ ssh -p 23231 localhost repo help Manage repositories Usage: ssh -p 23231 localhost repo [command] Aliases: repo, repos, repository, repositories Available Commands: blob Print out the contents of file at path branch Manage repository branches collab Manage collaborators create Create a new repository delete Delete a repository description Set or get the description for a repository hide Hide or unhide a repository import Import a new repository from remote info Get information about a repository list List repositories mirror Set or get a repository mirror property private Set or get a repository private property project-name Set or get the project name for a repository rename Rename an existing repository tag Manage repository tags tree Print repository tree at path Flags: -h, --help help for repo Use "ssh -p 23231 localhost repo [command] --help" for more information about a command. ``` ### 创建仓库 要创建仓库，首先确保您是注册用户。使用 `repo create ` 命令创建新仓库： ``` # 创建新仓库 ssh -p 23231 localhost repo create icecream # 创建带描述的仓库 ssh -p 23231 localhost repo create icecream '-d "This is an Ice Cream description"' # ... 和项目名称 ssh -p 23231 localhost repo create icecream '-d "This is an Ice Cream description"' '-n "Ice Cream"' # 我需要我的仓库是私有的！ ssh -p 23231 localhost repo create icecream -p '-d "This is an Ice Cream description"' '-n "Ice Cream"' # 需要帮助？ ssh -p 23231 localhost repo create -h ``` 或者，如果您有写访问权限，可以将您的 Soft Serve 服务器作为远程添加到任何现有仓库，并推送远程： ``` git remote add origin ssh://localhost:23231/icecream ``` 添加远程后，继续推送。如果服务器上不存在该仓库，它将被创建。 ``` git push origin main ``` ### 嵌套仓库 仓库也可以嵌套： ``` # 创建新的嵌套仓库 ssh -p 23231 localhost repo create charmbracelet/icecream # 或 ... git remote add charm ssh://localhost:23231/charmbracelet/icecream git push charm main ``` ### 镜像 您还可以 *导入* 来自任何公共远程的仓库。使用 `repo import` 命令。 ``` ssh -p 23231 localhost repo import soft-serve https://github.com/charmbracelet/soft-serve ``` 使用 `--mirror` 或 `-m` 将仓库标记为 *pull* 镜像。 ### 删除仓库 您可以使用 `repo delete ` 命令删除仓库。 ``` ssh -p 23231 localhost repo delete icecream ``` ### 重命名仓库 使用 `repo rename ` 命令重命名现有仓库。 ``` ssh -p 23231 localhost repo rename icecream vanilla ``` ### 仓库协作者 有时您想限制对某些仓库的写访问。这可以通过向您的仓库添加协作者来实现。 使用 `repo collab ` 命令管理仓库协作者。 ``` # 添加软服协作者 ssh -p 23231 localhost repo collab add soft-serve frankie # 添加具有特定访问级别的协作者 ssh -p 23231 localhost repo collab add soft-serve beatrice read-only # 移除协作者 ssh -p 23231 localhost repo collab remove soft-serve beatrice # 列出协作者 ssh -p 23231 localhost repo collab list soft-serve ``` ### 仓库元数据 您还可以使用 `repo ` 命令更改仓库的描述、项目名称、是否为私有等。 ``` # 为仓库设置描述 ssh -p 23231 localhost repo description icecream "This is a new description" # 隐藏仓库从列表中 ssh -p 23231 localhost repo hidden icecream true # 列出仓库信息（分支、标签、描述等） ssh -p 23231 localhost repo icecream info ``` 要使仓库私有，请使用 `repo private [true|false]`。私有仓库只能由管理员和协作者访问。 ``` ssh -p 23231 localhost repo private icecream true ``` ### 仓库分支和标签 使用 `repo branch` 和 `repo tag` 列出和删除分支或标签。您还可以使用 `repo branch default` 设置或获取仓库默认分支。 ### 仓库树 要打印项目的文件树，只需使用 `repo tree` 命令以及作为 SSH 命令到您的 Soft Serve 服务器的仓库名称： ``` ssh -p 23231 localhost repo tree soft-serve ``` 您还可以指定子路径和特定的引用或分支。 ``` ssh -p 23231 localhost repo tree soft-serve server/config ssh -p 23231 localhost repo tree soft-serve main server/config ``` 从那里，您可以使用 `repo blob` 命令打印单个文件： ``` ssh -p 23231 localhost repo blob soft-serve cmd/soft/main.go ``` 您可以使用 `-c` 标志启用语法着色，并使用 `-l` 打印行号： ``` ssh -p 23231 localhost repo blob soft-serve cmd/soft/main.go -c -l ``` 使用 `--raw` 打印原始文件内容。这对于转储二进制数据很有用。 ### 仓库 webhooks Soft Serve 支持使用 `repo webhook` 命令的仓库 webhooks。您可以为不同的仓库事件（如 _push_、_collaborators_ 和 _branch_tag_create_ 事件）创建和管理 webhooks。 ``` Manage repository webhooks Usage: ssh -p 23231 localhost repo webhook [command] Aliases: webhook, webhooks Available Commands: create Create a repository webhook delete Delete a repository webhook deliveries Manage webhook deliveries list List repository webhooks update Update a repository webhook Flags: -h, --help help for webhook ``` ## Soft Serve TUI Soft Serve TUI 主要用于通过 SSH 浏览仓库。您还可以使用它使用 `soft browse` 浏览本地仓库或在 Git 仓库中运行 `soft`。 ``` ssh localhost -p 23231 ``` 您还可以“链接”到特定的仓库： ``` ssh -p 23231 localhost -t soft-serve ``` 您可以通过 SSH 复制文本到您的剪贴板。例如，您可以在菜单中按 c 键复制克隆命令 [^osc52]。 [^osc52]： 通过 SSH 复制取决于您的终端对 OSC52 的支持。有关更多信息，请参阅 [go-osc52](https://github.com/aymanbagabas/go-osc52)。 ## 钩子 Soft Serve 支持 git 服务器端钩子 `pre-receive`、`update`、`post-update` 和 `post-receive`。这意味着您可以在仓库推送事件上定义自己的钩子。钩子可以是按仓库定义的钩子，也可以是全局钩子，它为所有仓库运行。 您可以在仓库的 `hooks` 目录下找到按仓库定义的钩子。 全局钩子可以在您的 `SOFT_SERVE_DATA_PATH` 目录下的 `hooks` 中找到。定义全局钩子对于您想要运行 CI/CD 等情况很有用。 以下是一个在收到推送事件后发送消息的示例。创建一个可执行文件 `/hooks/update`： <

标签：内存分配, 日志审计, 网络安全研究