前置:02 从零跑起来。读完你会知道:配置怎么组织、每个键什么语义、密钥怎么换(runbook 级)、启动序列是什么、上线前要过哪些可执行的检查。
服务配置内嵌在二进制里(apps/admin/assets/,include_str! 编译期打包),启动时环境变量优先覆盖——单二进制即可部署,改配置不用改文件:
| 文件 | 内容 | 读取处 |
|---|---|---|
server.yaml |
装配文档(见 §2) | main.rs 的 include_str! |
auth.yaml |
鉴权面:JWT 算法与双钥、authz 引擎类型 | config.rs |
data.yaml |
PostgreSQL 连接、Redis 连接、迁移开关 | config.rs |
oss.yaml |
MinIO endpoint / 桶凭据 / 上传下载 host | config.rs |
jwt_public_key.pem |
校验公钥兜底(auth.yaml 未配 public_key 时用) | main.rs 的 include_bytes! |
覆盖的优先级语义有个三级结构,值得背下来:
- 代码默认值 < yaml < 环境变量。例:令牌有效期的代码默认是 access 900s / refresh 7 天,
auth.yaml把它改成 5400s(1.5h)/ 43200s(12h),环境变量再改就赢; - 布尔只认
true/1(RUSHWIND_DATABASE_MIGRATE写yes不生效); - 空值处理分型:字符串类(
RUSHWIND_REDIS_ADDR等)环境变量设成空串也算覆盖;密钥与 endpoint 类用"非空才覆盖"(env_non_empty),设空等于没设——不会把密钥清掉。
一个生命周期、四个 transport——部署形态直接读这份文档就能还原。下面是全量真实文件加注解:
app:
name: admin # 进程名
version: 0.1.0
servers:
- kind: http # transport ①:REST 主服务
bind: ":7788"
edge:
timeout: 10s # 请求预算:整条链(bind→gate→handler→审计)的墙钟上限
cors:
# 前端 refresh token 走 HttpOnly Cookie(withCredentials=true),
# 预检响应必须带 Access-Control-Allow-Credentials: true
credentials: true
# compat 选择 gorilla 兼容层(发射规则与参照系逐字节一致)。
compat: true
headers: # 预检放行的请求头——登录链的新头必须登记在这里
- "X-Requested-With"
- "X-Request-ID"
- "Content-Type"
- "Authorization"
- "X-Captcha-Id"
- "X-Captcha-Value"
methods: [ "GET", "POST", "PUT", "DELETE", "HEAD", "OPTIONS" ]
origins:
# 生产前端三套域名 + 本地开发五个端口——部署时只保留你的域名
- "https://vben.admin.rushwind.cloud"
- "https://ele.admin.rushwind.cloud"
- "https://react.admin.rushwind.cloud"
- "http://localhost:5666"
- "http://localhost:5777"
- "http://localhost:5888"
- "http://localhost:5667"
- "http://localhost:5778"
route_packs:
- name: admin-surface # admin 契约的 59 个服务面
settings:
enable_swagger: true # /q/swagger-ui(生产建议关)
enable_redoc: true # /q/redoc(生产建议关)
- name: business-surface # 业务模块面:同 http server、同 edge,无 docs 设置节点
- kind: admin-sse # transport ②:SSE 通知服务
addr: ":7789" # 独立端口——网关放行与超时按长连接处理
path: "/events" # 订阅路径(前端 .env.production 的 VITE_SSE_URL 对齐它)
- kind: admin-tasks # transport ③:任务队列 worker(apalis-postgres,队列名 default)
- kind: cron # transport ④:cron 生产者
endpoint: cron://admin
jobs:
- tenant_expiry_scan # 每小时整点:过期租户 ON→EXPIRED
- audit_log_archive # 每日 03:30:归档投递占位(见 §8)
- sys_tasks_periodic # 每分钟滴答:重读 sys_tasks 的 PERIODIC 行按各自 cron 投递三个 cron 都注册在 apalis.rs::schedule_registry(任务监控的 inspect 面读它),worker 按 job 名分发;sys_tasks_periodic 是"任务管理页配的任务为何不用重启就生效"的全部机制。
loader(config.rs + crypto.rs)认的键就这 12 个,生产必改列给出改谁:
| 变量 | 覆盖什么 | 默认值 | 生产 |
|---|---|---|---|
RUSHWIND_DATABASE_SOURCE |
数据库连接(必须 URL 形式;本机开发加 ?sslmode=disable) |
yaml:host=postgres … dbname=rushwind_admin |
必改 |
RUSHWIND_DATABASE_MIGRATE |
启动迁移开关(true/1) | yaml migrate: true |
策略化(见 §9) |
RUSHWIND_REDIS_ADDR |
Redis 地址 | redis:6379 |
必改 |
RUSHWIND_REDIS_PASSWORD |
Redis 密码 | yaml 演示口令 | 必改 |
RUSHWIND_OSS_ENDPOINT |
MinIO endpoint(宿主侧跑容器时用它指到发布端口,不落网络别名) | yaml minio:9000 |
按拓扑 |
RUSHWIND_AUTH_JWT_PRIVATE_KEY |
RS256 签发私钥(PEM 全文注入,覆盖 auth.yaml) | auth.yaml 演示钥 | 必改(§5) |
RUSHWIND_AUTH_JWT_PUBLIC_KEY |
RS256 校验公钥(同上;不设则用 auth.yaml / 兜底 pem 文件) | 演示钥 | 必改(§5) |
RUSHWIND_ACCESS_TOKEN_EXPIRES_SECS |
access 令牌秒数 | yaml 5400(代码兜底 900) | 按安全策略 |
RUSHWIND_REFRESH_TOKEN_EXPIRES_SECS |
refresh 令牌秒数 | yaml 43200(代码兜底 7 天) | 按安全策略 |
RUSHWIND_CAPTCHA_REQUIRED_FAILURES |
渐进式验证码阈值:同一 ip+用户名登录失败达此次数后要求验证码(限定 1–4,越界收敛) | 3 | 可调 |
RUSHWIND_PASSWORD_RSA_PRIVATE_KEY |
口令传输信封的 RSA 私钥(PEM,单行 \n 转义可注入) |
仓内开发私钥 | 必改(§5) |
RUSHWIND_CRYPTO_KEY |
enc: 静密钥(MFA secret 落库的 AES-256-GCM) |
未设=明文存储 | 必改 |
三处边界要知情:
- MinIO 的 access_key / secret_key 没有 env 覆盖键——只能改
oss.yaml后重建镜像(或挂载替换该文件);只有 endpoint 有RUSHWIND_OSS_ENDPOINT; RUSHWIND_CAPTCHA_REQUIRED_FAILURES的合法域是 1–4:clamp(1, 4)会把 0 和 100 都收敛进界,不报错;- 换 JWT 私钥 = 全员下线(旧 access token 全部验签失败)——轮换窗口要选维护时段。
Config::load(yaml + env)→ 开发私钥告警检查 → JWT 校验引擎(RS256)
→ AppState::connect(Postgres 池 25/25、连接超时 10s;Redis 连接管理器;
JWT 签发引擎——私钥缺失启动即退;五桶 MinIO 引擎逐桶建,冲突=已存在即好)
→ migrate(database.migrate 开关:admin 链 → 模块链)→ seed(幂等播种:admin → 模块)
→ TaskQueue(apalis-postgres,队列 default)→ Bootstrap:route_pack ×2 + cron ×3 + 工厂 ×2
→ build().await → run(生命周期持 OS 信号关停路径)
对应源文件 apps/admin/src/main.rs(百行上下,值得整个读一遍)。要点:
- 中间件不可达时启动即退出——Postgres/Redis 连不上、JWT 私钥缺失都在
connect阶段Err返回,把"配置错了"拦在启动期,不带病运行; enable_swagger/enable_redoc生产建议关闭(文档端点免鉴权,/q/openapi.yaml会把全部契约面吐出去);- 反向代理注意:SSE 是独立端口(:7789)的长连接流,网关侧不要缓冲响应体、超时要放宽;前端经 Cookie 跨域携带 refresh 令牌,代理必须保留
Set-Cookie与Origin相关头。Cookie 的Secure标记按请求头x-forwarded-proto自适应——代理必须透传这个头,否则 HTTPS 部署下 Cookie 语义降级。
auth.yaml 内嵌的 JWT 双钥是演示密钥,随源码公开,生产必须更换:
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out jwt_private_key.pem
openssl pkey -in jwt_private_key.pem -pubout -out jwt_public_key.pem经 RUSHWIND_AUTH_JWT_PRIVATE_KEY / RUSHWIND_AUTH_JWT_PUBLIC_KEY 注入(PEM 全文注入,换行用 \n 转义成单行即可),或替换镜像内的 assets 后重建。注入自检:私钥格式错会在启动的 with_rsa_private_key_from_pem 处直接失败退出——启动成功即格式正确。
启动时有一行硬告警:
⚠️ RUSHWIND_PASSWORD_RSA_PRIVATE_KEY 未配置,口令传输解密仍在使用内置开发私钥,生产环境必须替换
不看日志就上线 = 任何拿到源码的人都能解开你站上的口令信封(crypto.rs::using_dev_password_private_key 做的是密码学等价判定,不是有没有设环境变量)。轮换三步:
- 生成一对新的 RSA-2048:
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out password.pem与openssl pkey -in password.pem -pubout -out password_pub.pem; - 后端注入
RUSHWIND_PASSWORD_RSA_PRIVATE_KEY(单行\n转义 PEM); - 前端同步换公钥:
frontend/admin/react/.env的VITE_PASSWORD_RSA_PUB换成新公钥 base64 并重新构建——前后端是同对密钥的两半,只换一半登录链就断了。公钥本来就是公开半,它进前端仓库是设计使然。
传输层还有个 legacy 通道:无 rsa-v1: 前缀的载荷按 base64(AES-128-CBC(key=IV=默认钥)) 解——默认钥 f51d66a73d8a0927 与前端 .env 的 VITE_AES_KEY 同值、随源码公开。rsa-v1 信封是主通道(前端 WebCrypto 发射),legacy 只为过渡期兼容;确认所有前端快照都走 rsa-v1 后,legacy 载荷自然不会再出现。
RUSHWIND_CRYPTO_KEY 是 32 字节密钥的 env 来源:设置后 MFA secret 以 enc: 前缀 AES-256-GCM 落库;未设置则明文。在第一批用户绑定 TOTP 之前定下这把钥——中途引入只会影响新写的行,密钥丢失 = 所有 enc: secret 无法解出,等于全员重新绑定。
data.yaml / oss.yaml 的演示口令、种子管理员 admin 的初始口令(首登即改)。refresh Cookie 的 Secure 标记按部署 TLS 自适应——生产务必走 HTTPS,否则 Cookie 语义降级。
oss:
minio:
endpoint: "minio:9000" # S3 引擎连接地址(path-style 寻址,MinIO 要求)
upload_host: "minio:9000" # 预留字段(当前无消费方)
download_host: "minio:9000" # 生成下载链接的主机——改成外部可达域名
access_key: "root" # 演示凭据,必改(无 env 覆盖键)
secret_key: "*Abcd123456" # 同上
token: ""
use_ssl: false- 五分类桶:文件服务按 MIME 嗅探结果路由到五个桶——
images / videos / audios / docs / files(OssBuckets::NAMES,image/*→images、video/*→videos、audio/*→audios、文本/PDF/Office→docs、其余→files)。启动时逐桶create_bucket(已存在冲突即视为成功,幂等),MinIO 侧无需预建; - host 语义:
endpoint是服务端引擎连的地址(容器网络名即可);download_host拼进落库的下载链接{download_host}/{bucket}/{object}——生产要改成浏览器可达的地址(如经反代暴露的 MinIO 域名);嗅探看魔数不看客户端声明的 MIME,改后缀绕不过桶路由; - 未配置 oss 段时退化为本地磁盘镜像(
./data/files/<bucket>/),元数据语义一致——单机演示够用,生产别这么跑。
cd frontend/admin/react
pnpm install && pnpm build # = vite build --mode production,产物 dist/生产构建启用 CSP、X-Frame-Options、HSTS 等安全响应头,出处有两处,各管一半:
- CSP meta:
build/plugins/csp.ts在构建期向index.html注入Content-Security-Policymeta——script-src 'self'加上对页内内联脚本(主题预绘)逐个计算的sha256-白名单。dev 构建跳过(HMR 内联脚本会被拦白屏)。meta CSP 不支持frame-ancestors,点击劫持防护仍需部署侧响应头; - 响应头:
scripts/deploy/nginx.conf(仓内是静态站参考配置,:8080)——X-Frame-Options: DENY、X-Content-Type-Options: nosniff、Referrer-Policy: strict-origin-when-cross-origin、Strict-Transport-Security: max-age=63072000; includeSubDomains、meta 之外的 CSP 补充(base-uri 'self'; object-src 'none'; frame-ancestors 'none')。不要在这个头里重复声明 script-src:多 CSP 策略浏览器取交集,meta 里的 sha256 白名单会被无哈希的重复声明重新收窄、内联主题脚本再度被拦。
.env.production 决定生产指向:
VITE_API_URL="/"
VITE_SSE_URL="/events"两个都是同源相对路径——生产需要网关把 API 与 SSE 转发到后端(对照 dev 的 VITE_PROXY='[["/admin", "http://127.0.0.1:7788/"]]')。nginx 反代形态(示例,接到你的静态站 server 块):
# REST 主面(含业务模块前缀 /template/ 等——每个业务模块一个前缀,照抄加行)
location ~ ^/(admin|template)/ {
proxy_pass http://admin-backend:7788;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme; # Cookie Secure 自适应就靠它
}
# SSE:独立端口的长连接,禁缓冲、放宽超时
location /events {
proxy_pass http://admin-backend:7789;
proxy_http_version 1.1;
proxy_set_header Connection "";
proxy_buffering off;
proxy_read_timeout 3600s;
}前端与后端是零改动契约:后端 CORS 白名单里加上你的前端域名即可(server.yaml 的 edge.cors.origins)。
- 数据库定时备份走任务系统的
backup任务类型:在任务管理页建 PERIODIC 任务、填 cron 即得定时作业。如实说明:worker 目前对backup(同批还有broadcast_message/script_task)只记录"任务已触发 + payload",不执行真实备份动作——"任务面已接线、执行器是占位",pg_dump 语义的备份作业是规划项。生产数据库备份请先落在 DB 侧工具(pg_dump 定时/WAL 归档),任务面留作触发入口; - 审计侧的
audit_log_archive系统作业(每日 03:30)当前只做投递占位:导出与清理尚未实现,JSONL 归档是规划项(第 7 章),库内留存策略是现阶段的唯一生效面; - 对象存储(MinIO)按桶前缀生命周期策略另行配置。
每项带验证命令——绿的才算过:
-
JWT 双钥已更换(演示钥下线):
grep -c "BEGIN PRIVATE KEY" your.env确认注入的是新钥;启动日志无 JWT 相关错误 -
口令信封私钥已换:启动日志没有
RUSHWIND_PASSWORD_RSA_PRIVATE_KEY 未配置告警行;前端VITE_PASSWORD_RSA_PUB与后端私钥同对(登录一次即验证) -
RUSHWIND_CRYPTO_KEY已设置,且在用户绑定 MFA 前定下 -
Redis / MinIO 凭据全部改掉(MinIO 凭据改
oss.yaml重建镜像);server.yamlCORS origins 改为生产前端域名:curl -i -X OPTIONS -H "Origin: https://your.frontend.example" \ -H "Access-Control-Request-Method: POST" \ http://<backend>:7788/admin/v1/captcha # 响应头应含 Access-Control-Allow-Origin: https://your.frontend.example
-
swagger/redoc 关闭(或置于内网/鉴权代理后):
curl -I http://<backend>:7788/q/swagger-ui # 期望 404/405 而不是 200
-
REST 探活(免鉴权端点):
curl -s http://<backend>:7788/admin/v1/captcha | head -c 200 # 期望 JSON:{"captchaId":"…","imageBase64":"data:image/png;base64,…"}
-
SSE 端口经网关放行且未被缓冲:
curl -i -N http://<backend>:7789/events # 未带 token:应立即收到错误响应(UNAUTHORIZED 语义)而不是挂死/404 # ——端口与路径可达即探活成功
-
全链 HTTPS(Cookie
Secure生效、口令传输加密有意义的前提;反代透传x-forwarded-proto) -
中间件地址与凭据经环境变量注入,未落在镜像层
-
database.migrate策略明确:首次部署 true 拉起 schema,之后迁移收敛到发布流程(关掉开关、迁移随发布脚本跑)。幂等自证——重启一次,账本行数不变:# 两次启动之间跑两次,行数应一致: psql "$RUSHWIND_DATABASE_SOURCE" -c \ "SELECT (SELECT count(*) FROM seaql_migrations) AS admin_chain, (SELECT count(*) FROM seaql_migrations_module_template) AS module_chain;"
种子同为幂等(自然键/固定键判存,重复启动行数稳定):
psql "$RUSHWIND_DATABASE_SOURCE" -c \ "SELECT count(*) FROM sys_menus WHERE module='DASHBOARD';" # 前后对比,均为 2
-
备份已落在 DB 侧工具(任务面
backup执行器是占位),并试跑一次恢复 -
种子管理员口令已改,MFA 已绑定(绑定前
RUSHWIND_CRYPTO_KEY必须已设,见 §5.3)
- 单二进制 + 内嵌配置 + 环境覆盖,部署面收敛到一份装配文档;优先级是"代码默认 < yaml < env",布尔只认 true/1,密钥类空值不覆盖;
- 演示密钥是随源码公开的,上线检查单第一项永远是换钥——JWT 双钥、口令信封私钥(带启动告警自检)、MFA 静密钥三把一起换;
- 四 transport 形态决定了网关配置的两处特殊点:SSE 长连接(:7789,禁缓冲)与 Cookie 透传(
x-forwarded-proto); - 任务系统的
backup与audit_log_archive都是"面已接线、执行器占位"——真实的备份与归档落 DB 侧工具,别被任务页的存在感骗了。
—— 教程完。回头可按 tutorial/README.md 的角色路线重读,或进 docs/README.md 的工程档案深读各子系统。