快速部署指南

本指南帮助你在 10 分钟内将 RustBill 部署到一台全新的 Ubuntu 服务器（20.04 / 22.04 / 24.04）。

1. 二进制部署（推荐）

RustBill 提供交互式部署脚本，一行命令完成全部初始化：

bash <(curl -fsSL https://raw.githubusercontent.com/zyxisme/rustbill-releases/main/deploy.sh)

脚本会自动完成以下步骤：

• 检测系统类型和架构，下载对应的预编译二进制
• 生成默认配置文件 config.toml
• 创建 systemd 服务单元
• 初始化 PostgreSQL 数据库（可选）
• 配置防火墙规则

非交互模式（CI / 自动化脚本）：

bash <(curl -fsSL https://raw.githubusercontent.com/zyxisme/rustbill-releases/main/deploy.sh) -- -y

脚本执行完毕后，二进制位于 /usr/local/bin/rustbill-server，配置文件位于 /etc/rustbill/config.toml。

手动下载

如需手动安装，从 GitHub Releases 下载对应平台的 tar.gz，解压后将二进制放入 /usr/local/bin/：

# 示例：x86_64 Linux
curl -L -o rustbill.tar.gz https://github.com/zyxisme/rustbill-releases/releases/latest/download/rustbill-x86_64-unknown-linux-gnu.tar.gz
tar xzf rustbill.tar.gz
sudo mv rustbill-server rustbill-cli /usr/local/bin/

2. PostgreSQL 安装

RustBill 需要 PostgreSQL 16+。

Ubuntu 22.04 / 24.04

# 安装
sudo apt update && sudo apt install -y postgresql

# 启动并设为开机自启
sudo systemctl enable --now postgresql

创建用户和数据库

sudo -u postgres psql <<EOF
CREATE USER rustbill WITH PASSWORD 'your-db-password';
CREATE DATABASE rustbill OWNER rustbill;
GRANT ALL PRIVILEGES ON DATABASE rustbill TO rustbill;
EOF

注意：将 your-db-password 替换为强密码。RustBill 启动时会自动执行数据库迁移（创建表结构），无需手动运行 SQL 文件。

3. 最小配置

RustBill 默认读取 /etc/rustbill/config.toml，并可选叠加 /etc/rustbill/config.local.toml（Figment 层叠合并）。

配置文件路径

最小化 config.toml

创建 /etc/rustbill/config.toml，写入以下内容（仅 3 个必填项）：

sudo mkdir -p /etc/rustbill /etc/rustbill/plugins

# 生成 JWT secret
JWT_SECRET=$(openssl rand -base64 64)

sudo tee /etc/rustbill/config.toml > /dev/null <<EOF
[server]
host = "127.0.0.1"
port = 50051

[db]
url = "postgres://rustbill:your-db-password@localhost/rustbill"

[jwt]
secret = "$JWT_SECRET"

[bootstrap]
admin_password = "your-admin-password"
EOF

必须修改的字段：

• [db].url — 将 your-db-password 替换为上一步创建的数据库密码
• [bootstrap].admin_password — 替换为管理员初始密码（首次登录后建议修改）

完整配置参考

更多配置项（Redis、速率限制、CORS、Session 等）参见 config.example.toml：

curl -fsSL https://raw.githubusercontent.com/zyxisme/rustbill/refs/heads/main/config.example.toml

4. 启动服务

创建 systemd 服务

sudo tee /etc/systemd/system/rustbill-server.service > /dev/null <<'EOF'
[Unit]
Description=RustBill Server
After=network.target postgresql.service
Requires=postgresql.service

[Service]
Type=simple
User=rustbill
Group=rustbill
ExecStart=/usr/local/bin/rustbill-server
WorkingDirectory=/etc/rustbill
Restart=always
RestartSec=5
Environment=RUST_LOG=rustbill_server=info

# 安全加固
NoNewPrivileges=yes
ProtectSystem=strict
ProtectHome=yes
ReadWritePaths=/etc/rustbill
ReadOnlyPaths=/usr/local/bin

[Install]
WantedBy=multi-user.target
EOF

创建运行用户并设置权限

sudo useradd -r -s /bin/false -d /etc/rustbill rustbill
sudo chown -R rustbill:rustbill /etc/rustbill

启动并验证

# 重载 systemd，启动服务
sudo systemctl daemon-reload
sudo systemctl enable --now rustbill-server

# 检查状态
sudo systemctl status rustbill-server

# 查看日志
sudo journalctl -u rustbill-server -f

健康检查

curl http://127.0.0.1:50051/health
# 预期输出：OK

5. Caddy 反代（推荐）

Caddy 原生支持 HTTP/3（QUIC）和自动 Let’s Encrypt 证书，是 RustBill 推荐的反向代理。

安装 Caddy

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update && sudo apt install -y caddy

最小 Caddyfile

创建 /etc/caddy/Caddyfile（将 your-domain.com 替换为你的域名）：

your-domain.com {
    # gRPC 后端（支持 gRPC-Web）
    handle /rustbill.* {
        reverse_proxy 127.0.0.1:50051
    }

    # 健康检查直通
    handle /health {
        reverse_proxy 127.0.0.1:50051
    }

    # Admin SPA（内嵌于 RustBill 二进制）
    handle /admin* {
        reverse_proxy 127.0.0.1:50051
    }

    # Customer 前台（独立静态文件部署）
    handle {
        root * /var/www/rustbill-consumer
        try_files {path} /index.html
        file_server
    }
}

Caddy 自动申请 Let’s Encrypt 证书，启用 HTTP/3（QUIC）。唯一前提是域名 DNS 已指向服务器 IP。

重载配置

sudo systemctl reload caddy

6. 前端部署

Admin 管理后台

Admin SPA 已内嵌在 rustbill-server 二进制中，无需额外部署。 浏览器访问 https://your-domain.com/admin 即可使用。

如修改了 [server].admin_path 配置项，访问路径需同步调整。

Customer 前台

Customer SPA 是独立的前端应用，需单独构建和部署：

# 从 GitHub Releases 下载预构建的静态文件
curl -L -o consumer-dist.tar.gz https://github.com/zyxisme/rustbill-releases/releases/latest/download/consumer-dist.tar.gz

sudo mkdir -p /var/www/rustbill-consumer
sudo tar xzf consumer-dist.tar.gz -C /var/www/rustbill-consumer
sudo chown -R caddy:caddy /var/www/rustbill-consumer

配置 gRPC 端点

Customer SPA 运行时从 config.json 读取后端地址。编辑 /var/www/rustbill-consumer/config.json：

{
  "grpcEndpoint": "https://your-domain.com",
  "appTitle": "RustBill Cloud",
  "adminUrl": "https://your-domain.com/admin"
}

字段说明：

• grpcEndpoint — gRPC 服务的完整 origin（含 https://），Customer SPA 通过此地址发起 gRPC-Web 请求
• appTitle — 页面标题
• adminUrl — 管理后台跳转链接（前台登录页展示）

本地构建（可选）

如需自定义主题/品牌，从源码构建：

git clone https://github.com/zyxisme/rustbill.git
cd rustbill/web-consumer
npm install
cp brand.yaml.example brand.yaml    # 按需编辑品牌配置
npm run build
# 产物在 dist/ 目录

7. 首次登录

1. 浏览器打开 https://your-domain.com/admin
2. 使用 [bootstrap].admin_password 中设置的用户名和密码登录
   • 默认用户名：admin
   • 密码：配置文件中 admin_password 的值
3. 登录后建议立即修改密码：
   • 导航到 系统管理 → 用户管理
   • 点击当前用户，修改密码

首次登录后，你可以在 Admin 后台完成以下操作：

• 添加商品 — 商品管理 → 新建商品
• 配置插件 — 基础设施 → 插件管理 → 创建接口实例
• 管理客户 — 客户管理 → 新建客户

8. 验证清单

部署完成后，逐项验证以下功能正常：

常见问题

服务启动失败

# 查看详细日志
sudo journalctl -u rustbill-server -n 50 --no-pager

常见原因：

• 数据库连接失败 — 检查 config.toml 中 [db].url 是否正确，PostgreSQL 是否运行
• JWT secret 为空 — [jwt].secret 必须设置且不能为 "change-me-in-production"
• 插件目录不可写 — 确保 plugins/ 目录存在且 rustbill 用户有读写权限

Caddy 证书申请失败

# 查看 Caddy 日志
sudo journalctl -u caddy -n 50 --no-pager

常见原因：

• DNS 未解析 — 域名必须已指向服务器公网 IP
• 80/443 端口被占用 — 确保 Nginx/Apache 未占用这些端口
• 防火墙未开放 — 需放行 80/tcp 和 443/tcp+udp

防火墙配置

# UFW
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 443/udp    # HTTP/3 QUIC
sudo ufw enable

修改 bootstrap 密码

RustBill 只在首次启动时（admin_users 表为空）使用 [bootstrap].admin_password 创建 admin 用户。如需重置：

1. 登录 Admin 后台 → 用户管理 → 修改密码
2. 或通过 CLI：rustbill-cli user passwd admin --new-password "xxx"

更新 RustBill

# 重新运行部署脚本（自动下载最新版本并替换二进制）
bash <(curl -fsSL https://raw.githubusercontent.com/zyxisme/rustbill-releases/main/deploy.sh)

# 重启服务
sudo systemctl restart rustbill-server

下一步

• 完整配置参考：配置文档
• 插件开发指南：插件开发
• 架构设计概览：架构设计
• API 文档：gRPC API