jocay/bolt
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity

docs: README 以一键安装为主线重新组织安装说明

Browse Source 
- 开头即给出 IPv4 / IPv6 一键安装命令、参数表与安装后的状态检查
- 新增连接 AI 客户端(带 Authorization 头)、更新、卸载、从源码构建的独立小节
- 说明 Release 目前提供的平台附件及其系统要求
- 部署细节集中到末尾:配置文件位置与修改方式、macOS launchd、systemd 手动部署、发布新版本流程

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
jocay
2026-10-18 11:01:09 +08:00
parent a8d6dd4b87
commit e2640dad57
1 changed files with 119 additions and 68 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+118 -67
View File
@@ -6,33 +6,118 @@
- **零框架**:手写 JSON-RPC 2.0 + MCP 协议 + Streamable HTTP 服务器,无 async runtime、无重量级依赖 - **零框架**:手写 JSON-RPC 2.0 + MCP 协议 + Streamable HTTP 服务器,无 async runtime、无重量级依赖
- **双传输**:`stdio`(本地 AI 客户端默认)与 `Streamable HTTP`(远程连接) - **双传输**:`stdio`(本地 AI 客户端默认)与 `Streamable HTTP`(远程连接)
## 快速开始 ## 安装
### 一键安装(Linux / macOS)
在目标设备上执行(需要 root;已经是 root 时去掉 `sudo`)。IPv4 网络用 `git.jocayn.qzz.io`,IPv6 网络用 `git.draws.qzz.io`:
```bash
# IPv4
curl -fsSL https://git.jocayn.qzz.io/jocay/bolt/raw/branch/main/deploy/install.sh | sudo sh -s -- --http 0.0.0.0:8080 --token 你的令牌
# IPv6
curl -fsSL https://git.draws.qzz.io/jocay/bolt/raw/branch/main/deploy/install.sh | sudo sh -s -- --http 0.0.0.0:8080 --token 你的令牌
```
脚本会:识别平台 → 从 Release 下载最新版二进制并校验 SHA-256 → 装到 `/usr/local/bin/bolt` → 写入配置 → 注册系统服务(Linux 为 systemd 的 `bolt`,macOS 为 launchd 的 `io.jocay.bolt`)→ 设置开机自启并启动。
- 目前 Release 提供 `linux-amd64`(glibc ≥ 2.28,Debian 10 / Ubuntu 18.10 及以上)和 `darwin-arm64`(macOS 11+,Apple Silicon);其他平台请[从源码构建](#从源码构建)后用 `--binary` 安装。
- 只在本机使用、或放在反向代理后面时,监听 `127.0.0.1:端口` 即可;直接对外监听 `0.0.0.0` 时务必设置 `--token`。
- 已安装的设备再次执行会被拒绝,以免按新参数重写配置时丢掉令牌。升级请用[更新](#更新),确实要重装加 `--reinstall`。
更多参数写在 `sh -s --` 之后,例如限制命令和文件目录:
```bash
curl -fsSL https://git.jocayn.qzz.io/jocay/bolt/raw/branch/main/deploy/install.sh | sudo sh -s -- \
--http 0.0.0.0:8080 --token 你的令牌 --allow "git,docker,ls" --file-root /srv/data
```
| 参数 | 含义 |
|---|---|
| `--http <addr>` | 监听地址,默认 `127.0.0.1:8080`;对外用 `0.0.0.0:8080` |
| `--token <t>` | Bearer 认证令牌(对外监听时必填) |
| `--allow <a,b>` / `--deny <a,b>` | 命令白/黑名单 |
| `--timeout-ms <n>` | 命令默认超时,默认 30000 |
| `--file-root <d1,d2>` | 文件功能允许访问的目录(配置 `--allow` 时必填,否则文件功能禁用) |
| `--max-upload <n>` | `PUT /files` 单次上传上限,默认 2G |
| `--version <tag>` | 安装指定版本,默认最新 |
| `--binary <路径或URL>` | 不从 Release 下载,改用本地二进制(如 `scp` 过去的)或指定 URL |
| `--reinstall` | 已安装时按本次参数重写配置 |
| `--no-start` / `--no-enable` | 只安装不启动 / 不设开机自启 |
环境变量:`BOLT_GIT_HOST` 指定下载站点(默认先试 `git.jocayn.qzz.io`,不通再试 `git.draws.qzz.io`),`BOLT_DL_URL` 直接指定二进制地址,`BOLT_DL_TOKEN` 用于私有仓库下载(与 `--token` 无关)。
装好后查看状态:
```bash
systemctl status bolt # Linux
sudo launchctl print system/io.jocay.bolt # macOS
```
### 连接 AI 客户端
```bash
# Claude Code 连接远程 bolt(带令牌)
claude mcp add --transport http bolt http://服务器:8080/mcp --header "Authorization: Bearer 你的令牌"
# 放在 HTTPS 反向代理后面时,直接用代理地址
claude mcp add --transport http bolt https://bolt.example.com/mcp --header "Authorization: Bearer 你的令牌"
```
其他 MCP 客户端按 Streamable HTTP 方式配置 `http://服务器:8080/mcp`,并加上 `Authorization: Bearer 你的令牌` 请求头。
### 更新
只替换二进制并重启服务,**保留现有配置**:
```bash
# IPv4
curl -fsSL https://git.jocayn.qzz.io/jocay/bolt/raw/branch/main/deploy/update.sh | sudo sh
# IPv6
curl -fsSL https://git.draws.qzz.io/jocay/bolt/raw/branch/main/deploy/update.sh | sudo sh
```
- 已是最新版本时直接跳过,不会自动降级;新版本服务起不来时自动回滚,旧版本备份在 `/usr/local/bin/bolt.bak`。
- 重启由独立进程完成,所以让 AI 通过 bolt 自己执行更新也安全(只是这次调用的连接会断开,稍后重连即可)。
- 可选参数(写在 `sh -s --` 之后):`--version v0.2.0` 安装指定版本,`--binary ./bolt` 使用本地二进制,`--force` 同版本也重装。
### 卸载
```bash
# IPv4
curl -fsSL https://git.jocayn.qzz.io/jocay/bolt/raw/branch/main/deploy/uninstall.sh | sudo sh
# IPv6
curl -fsSL https://git.draws.qzz.io/jocay/bolt/raw/branch/main/deploy/uninstall.sh | sudo sh
```
删除服务、二进制和备份,默认同时删除配置与日志;要保留配置加 `sh -s -- --keep-config`。
### 从源码构建
```bash ```bash
cargo build --release # 产物: target/release/bolt (~1MB) cargo build --release # 产物: target/release/bolt (~1MB)
``` ```
**本地模式(stdio)**:由 MCP 客户端拉起本进程 **本地模式(stdio)**:不需要安装服务,由 MCP 客户端直接拉起本进程
```bash ```bash
# Claude Code
claude mcp add --transport stdio bolt -- /abs/path/to/bolt claude mcp add --transport stdio bolt -- /abs/path/to/bolt
# 通用 MCP 客户端: {"mcpServers": {"bolt": {"command": "/abs/path/to/bolt"}}}
# 或通用 MCP 客户端配置
# {"mcpServers": {"bolt": {"command": "/abs/path/to/bolt"}}}
``` ```
**远程模式(Streamable HTTP)**:AI 通过网络连接 **远程模式(Streamable HTTP)**:直接前台运行
```bash ```bash
bolt --http 127.0.0.1:8080 # 仅本机 bolt --http 127.0.0.1:8080 # 仅本机
bolt --http 0.0.0.0:8080 --token mysecret # 对外 + Bearer 认证 bolt --http 0.0.0.0:8080 --token mysecret # 对外 + Bearer 认证
bolt --http 0.0.0.0:8080 --token mysecret --allow "git,docker,curl" --file-root /srv/data bolt --http 0.0.0.0:8080 --token mysecret --allow "git,docker,curl" --file-root /srv/data
# Claude Code 连接远程
claude mcp add --transport http bolt http://127.0.0.1:8080/mcp
``` ```
要注册成系统服务,把构建产物交给安装脚本:`sudo sh deploy/install.sh --binary target/release/bolt --http 0.0.0.0:8080 --token 你的令牌`。
## 工具 ## 工具
| 工具 | 说明 | | 工具 | 说明 |
@@ -140,56 +225,21 @@ python3 docs/bolt_http_test.py # HTTP 端到端(含 Mcp-Session-Id、/files
- Linux / macOS(完整功能:进程组杀、信号处理) - Linux / macOS(完整功能:进程组杀、信号处理)
- Windows(基础功能:`cmd /C`、`taskkill /T` 杀进程树、Ctrl+C 清理退出) - Windows(基础功能:`cmd /C`、`taskkill /T` 杀进程树、Ctrl+C 清理退出)
## 在其他设备上部署(一键脚本) ## 部署细节
脚本支持 Linux(systemd)和 macOS(launchd),自动识别 amd64 / arm64(Apple Silicon 即使在 Rosetta 终端中也优先选择 arm64),需要 root 权限。仓库公开,无需令牌;IPv4 网络用 `git.jocayn.qzz.io`,IPv6 网络用 `git.draws.qzz.io`(脚本下载二进制时先试 `git.jocayn.qzz.io`、不通再试 `git.draws.qzz.io`,协议族由 curl 自动选择,探测超时 15 秒)。 ### 配置文件与修改
| 操作 | IPv4 | IPv6 | | | Linux(systemd) | macOS(launchd) |
|---|---|---| |---|---|---|
| 安装 | `curl -fsSL https://git.jocayn.qzz.io/jocay/bolt/raw/branch/main/deploy/install.sh \| sudo sh -s -- --http 0.0.0.0:8080 --token 你的令牌` | `curl -fsSL https://git.draws.qzz.io/jocay/bolt/raw/branch/main/deploy/install.sh \| sudo sh -s -- --http 0.0.0.0:8080 --token 你的令牌` | | 二进制 | `/usr/local/bin/bolt` | `/usr/local/bin/bolt` |
| 更新 | `curl -fsSL https://git.jocayn.qzz.io/jocay/bolt/raw/branch/main/deploy/update.sh \| sudo sh` | `curl -fsSL https://git.draws.qzz.io/jocay/bolt/raw/branch/main/deploy/update.sh \| sudo sh` | | 配置 | `/etc/bolt.env`(`BOLT_*` 环境变量);监听地址在 `/etc/systemd/system/bolt.service` 的 `ExecStart` | `/Library/Application Support/bolt/io.jocay.bolt.plist`(开机自启时复制到 `/Library/LaunchDaemons/`) |
| 卸载 | `curl -fsSL https://git.jocayn.qzz.io/jocay/bolt/raw/branch/main/deploy/uninstall.sh \| sudo sh` | `curl -fsSL https://git.draws.qzz.io/jocay/bolt/raw/branch/main/deploy/uninstall.sh \| sudo sh` | | 日志 | `journalctl -u bolt -f` | `/var/log/bolt/stdout.log`、`/var/log/bolt/stderr.log` |
| 重启 | `sudo systemctl restart bolt` | `sudo launchctl kickstart -k system/io.jocay.bolt` |
- **安装**(`install.sh`):下载 Release 上最新版本的 `bolt-<平台>-<架构>` 附件(有 `SHA256SUMS` 附件时自动校验)→ 装到 `/usr/local/bin` → 写配置与服务 → 开机自启 → 启动。已安装的设备会拒绝执行,避免按新参数重写配置时丢掉令牌;确实要重装加 `--reinstall`。 Linux 上改完 `/etc/bolt.env` 后重启服务即可生效,可用的变量见 `deploy/bolt.env.example`。macOS 的两份 plist 需要保持一致,改参数建议用 `--reinstall` 重新执行安装脚本(记得带上原来的 `--token` 等参数)。两份配置均仅 root 可读写。
- **更新**(`update.sh`):只替换二进制并重启服务,**保留现有配置**;已是最新版本时直接跳过,不会自动降级。新版本服务起不来时自动回滚到旧版本(旧版本备份在 `/usr/local/bin/bolt.bak`)。重启由独立进程完成,所以通过 bolt 自身执行更新也安全(只是本次调用的连接会断开)。
- `--version v0.2.0` 安装指定版本,`--binary ./bolt` 使用本地二进制,`--force` 同版本也重装
- **卸载**(`uninstall.sh`):停止并删除服务、二进制和备份;默认同时删除配置与日志,加 `--keep-config` 保留。
- 环境变量:`BOLT_GIT_HOST` 指定下载站点,`BOLT_VERSION` 指定版本,`BOLT_DL_URL` 直接指定二进制地址,`BOLT_DL_TOKEN` 用于私有仓库下载。
传参写在 `sh -s --` 之后,例如:
```bash
curl -fsSL https://git.jocayn.qzz.io/jocay/bolt/raw/branch/main/deploy/install.sh | sudo sh -s -- \
--http 0.0.0.0:8080 --token 你的令牌 --allow "git,docker" --file-root /srv/data
curl -fsSL https://git.jocayn.qzz.io/jocay/bolt/raw/branch/main/deploy/update.sh | sudo sh -s -- --version v0.2.0
curl -fsSL https://git.jocayn.qzz.io/jocay/bolt/raw/branch/main/deploy/uninstall.sh | sudo sh -s -- --keep-config
```
安装参数(全部可选):
| 参数 | 含义 |
|---|---|
| `--http <addr>` | 监听地址,默认 `127.0.0.1:8080`;对外用 `0.0.0.0:8080` |
| `--token <t>` | Bearer 认证令牌(公网必填) |
| `--allow <a,b>` / `--deny <a,b>` | 命令白/黑名单 |
| `--timeout-ms <n>` | 默认命令超时 |
| `--file-root <d1,d2>` | 文件功能允许访问的目录(配置 `--allow` 时必填,否则文件功能禁用) |
| `--max-upload <n>` | `PUT /files` 单次上传上限(默认 2G) |
| `--binary <路径或URL>` | 跳过 Release 下载,用本地二进制(如 `scp` 过去的)或指定 URL |
| `--version <tag>` | 安装指定版本(默认最新) |
| `--reinstall` | 已安装时按本次参数重写配置 |
| `--no-start` / `--no-enable` | 只安装不启动 / 不设开机自启 |
### 发布新版本
在 Gitea 上新建 Release(tag 如 `v0.2.0`),上传附件 `bolt-linux-amd64`、`bolt-darwin-arm64`(以及需要的其他平台)和 `SHA256SUMS`(`sha256sum bolt-* > SHA256SUMS`)。脚本按 `/api/v1/repos/jocay/bolt/releases/latest` 识别最新版本,发布后各设备执行更新命令即可。
Linux 附件建议用 `cargo zigbuild --release --target x86_64-unknown-linux-gnu.2.28` 编译(只依赖 glibc 2.28,Debian 10 及以上都能运行);macOS 附件用 `cargo zigbuild --release --target aarch64-apple-darwin` 交叉编译,脚本安装时会在缺少签名时自动补 ad-hoc 签名。
### macOS(launchd) ### macOS(launchd)
脚本会创建以 root 运行的 launchd 系统服务 `io.jocay.bolt`。配置保存在 `/Library/Application Support/bolt/io.jocay.bolt.plist`,包含监听地址、认证令牌、命令规则和超时;启用开机自启时,脚本还会复制到 `/Library/LaunchDaemons/io.jocay.bolt.plist`。两份配置均仅 root 可读写。
`--no-enable` 只保留手动启动配置,取消本服务的开机配置,仍可立即启动;`--no-start` 本次不加载服务,已运行的本服务也会卸载,下次开机是否启动由 `--no-enable` 决定。两个参数可一起使用。 `--no-enable` 只保留手动启动配置,取消本服务的开机配置,仍可立即启动;`--no-start` 本次不加载服务,已运行的本服务也会卸载,下次开机是否启动由 `--no-enable` 决定。两个参数可一起使用。
```bash ```bash
@@ -200,16 +250,13 @@ sudo launchctl bootout system/io.jocay.bolt
# 停止后或使用 --no-start 安装后,手动加载并启动 # 停止后或使用 --no-start 安装后,手动加载并启动
sudo launchctl bootstrap system '/Library/Application Support/bolt/io.jocay.bolt.plist' sudo launchctl bootstrap system '/Library/Application Support/bolt/io.jocay.bolt.plist'
# 查看日志
sudo tail -f /var/log/bolt/stdout.log /var/log/bolt/stderr.log
``` ```
macOS 服务的工作目录为 `/var/root`,PATH 包含 `/opt/homebrew/bin` 和 `/opt/homebrew/sbin`,不会加载个人 shell 配置。 macOS 服务的工作目录为 `/var/root`,PATH 包含 `/opt/homebrew/bin` 和 `/opt/homebrew/sbin`,不会加载个人 shell 配置。
## systemd 服务部署(手动) ### systemd 手动部署
仓库内 `deploy/` 提供现成的部署文件: 不用安装脚本时,仓库内 `deploy/` 提供现成的部署文件:
```bash ```bash
sudo install -m 0755 target/release/bolt /usr/local/bin/bolt sudo install -m 0755 target/release/bolt /usr/local/bin/bolt
@@ -219,14 +266,18 @@ sudo systemctl daemon-reload
sudo systemctl enable --now bolt # 开机自启 + 立即启动 sudo systemctl enable --now bolt # 开机自启 + 立即启动
``` ```
常用管理命令: 服务特性:崩溃自动重启(`Restart=on-failure`,2 秒间隔)、优雅停机(SIGTERM 时杀掉所有子进程树)、日志进 journald、`LimitNOFILE=65536`。
```bash ### 发布新版本
systemctl status bolt # 查看状态
systemctl restart bolt # 重启(改完配置后)
systemctl stop bolt # 停止
systemctl disable bolt # 取消开机自启
journalctl -u bolt -f # 实时查看日志
```
特性:崩溃自动重启(`Restart=on-failure`,2 秒间隔)、优雅停机(SIGTERM 时杀掉所有子进程树)、日志进 journald、`LimitNOFILE=65536`。默认监听 `127.0.0.1:8080`,对外暴露前务必在 `/etc/bolt.env` 设置 `BOLT_TOKEN`。 1. 修改 `Cargo.toml` 的 `version`,提交并推送。
2. 编译附件(需要 [cargo-zigbuild](https://github.com/rust-cross/cargo-zigbuild) 与 zig):
```bash
cargo zigbuild --release --target x86_64-unknown-linux-gnu.2.28 # bolt-linux-amd64,只依赖 glibc 2.28
cargo zigbuild --release --target aarch64-apple-darwin # bolt-darwin-arm64,安装时缺少签名会自动补 ad-hoc 签名
sha256sum bolt-* > SHA256SUMS
```
直接 `cargo build` 的产物依赖构建机的 glibc 版本,拿到较老的系统上可能无法运行。
3. 在 Gitea 上新建 Release(tag 如 `v0.3.0`),上传 `bolt-linux-amd64`、`bolt-darwin-arm64` 和 `SHA256SUMS`。脚本按 `/api/v1/repos/jocay/bolt/releases/latest` 识别最新版本,发布后各设备执行[更新](#更新)命令即可。