前五篇的工程在本地跑得很好,第一次放到服务器就遇到一串问题。端口 18080 写在代码里,服务器上这个端口被别的服务占了,改端口要重新编译;容器启动后 SQLite 报「attempt to write a readonly database」,因为镜像用了只读文件系统且没有挂载可写目录;健康检查接口永远返回 200,数据库其实已经断开,负载均衡仍然把流量打进来;发布时直接杀进程,正在处理的请求收到连接重置。
这些问题有一个共同点:本地开发关注「功能对不对」,上线关注「环境变了还对不对」。配置、日志、健康检查、停机、权限、反向代理,每一项都只在真实部署环境里才会暴露。它们不属于业务代码,却决定了服务能不能稳定运行。
这篇把前五篇的代码收成一个可部署的进程:配置全部从环境变量来,日志走 tracing 并输出到 stdout,健康检查真正查库,停机时等请求处理完,构建用 release,容器用非 root 加可写数据目录,反向代理传真实 IP。需要提前说明:cargo build --release 的产物体积与启动耗时、Docker 镜像构建、systemd 与 Nginx 配置的实际运行,我都没有在本机实测,文中会逐项标注。
先看现象:上线阶段的九个典型故障
下面这张表按「上线后看到什么」组织。第三列尽量写成一条可以立刻执行的命令或观察点,避免停在「再查查」。
| 现象 | 真实原因 | 第一步查什么 |
|---|---|---|
| 换台机器就起不来,端口被占 | 端口写死在代码里,没有配置入口 | 看是否有 PORT 环境变量及默认值 |
启动报缺少 DATABASE_URL | 部署环境没有注入变量,或变量名拼错 | 看 systemd 的 Environment 或容器的 -e |
| 数据库挂了,健康检查仍返回 200 | 健康检查只返回固定 JSON,没有真正查库 | 看 handler 是否执行 SELECT 1 |
| 发布重启时用户收到连接重置 | 进程被直接杀死,没有优雅停机 | 看是否接 with_graceful_shutdown,停服信号是否传对 |
| 容器里 SQLite 报只读 | 根文件系统只读,或数据目录没有写权限 | 看挂载卷、目录属主和进程用户 |
| 日志进文件后带一堆转义字符 | tracing 默认输出 ANSI 颜色,未在非终端环境关闭 | 看 subscriber 是否设置 with_ansi(false) |
Nginx 后面拿到的客户端 IP 全是 127.0.0.1 | 反向代理没有传真实 IP 头,应用也没读 | 看 X-Real-IP、X-Forwarded-For |
| 容器里的时间比本地少 8 小时 | 容器默认 UTC,日志和业务时间没有统一口径 | 确认存储用 UTC、展示时再转本地时区 |
| release 二进制换机器跑不起来 | 构建机与运行机的 C 库版本不匹配 | 看动态链接依赖,或改用同基础镜像构建 |
这张表里最隐蔽的是第三条和第五条。健康检查返回 200 但数据库已断,监控会显示一切正常,直到用户报错;SQLite 只读不会在启动时报,往往是第一次写入才爆。两者都属于「配置看起来对,运行时才发现环境不对」,只能靠启动自检和真实请求覆盖。
配置:全部从环境变量来
配置的第一条纪律是「代码里不写死环境相关的东西」。端口、数据库地址、签名密钥、日志级别、外部服务地址,都应该在启动时从环境变量读取,代码只提供默认值或直接报错。这样同一份二进制可以在本机、测试、生产运行,不需要为每个环境重新编译。
下面的 Config 读取 PORT、DATABASE_URL、APP_SECRET 三个值。端口有默认值 18080,数据库和密钥缺失则直接失败;密钥还要求至少 32 字节,避免有人图省事填一个短字符串:
use std::env;
struct Config {
port: u16,
database_url: String,
app_secret: String,
}
impl Config {
fn from_env() -> Result<Self, String> {
let port = env::var("PORT")
.unwrap_or_else(|_| "18080".to_string())
.parse::<u16>()
.map_err(|_| "PORT must be a number".to_string())?;
let database_url = env::var("DATABASE_URL")
.map_err(|_| "DATABASE_URL is required".to_string())?;
let app_secret = env::var("APP_SECRET")
.map_err(|_| "APP_SECRET is required".to_string())?;
if app_secret.len() < 32 {
return Err("APP_SECRET must be at least 32 bytes".to_string());
}
Ok(Config {
port,
database_url,
app_secret,
})
}
}
启动时调用它,失败就把原因打到 stderr 并退出。不要用 unwrap 把错误吞成一行 panic,运维需要看到「缺哪个变量」,而不是「called Option::unwrap on None」:
let config = Config::from_env().unwrap_or_else(|error| {
eprintln!("config error: {error}");
std::process::exit(1);
});
本机启动时显式传环境变量,Windows PowerShell 的写法是:
$env:PORT="18080"
$env:DATABASE_URL="sqlite://app.db?mode=rwc"
$env:APP_SECRET="dev-secret-at-least-32-bytes-long"
cargo run
三个变量的用途不同。PORT 是监听端口,部署时由编排系统或运维分配;DATABASE_URL 是数据库连接串,SQLite 用 sqlite:// 加文件路径,PostgreSQL 的写法没有在本机实测;APP_SECRET 是令牌签名密钥,必须保密,不能进仓库、不能写进镜像。启动日志里只打印「密钥已加载」和长度,不要打印值。
Dockerfile 的 ENV。镜像层是可以被拉取和检查的,写进去等于公开。用运行时的环境变量、密钥管理服务或挂载文件注入;轮换密钥时按上一篇的双密钥方案过渡,避免所有用户同时掉登录。日志:tracing、EnvFilter 与结构化字段
部署阶段的依赖和前面一致,完整清单如下,日志相关的版本单独确认:
[dependencies]
axum = "0.8.9"
tokio = { version = "1", features = ["full"] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
sqlx = { version = "0.8.6", features = ["runtime-tokio", "sqlite", "derive"] }
tower-http = { version = "0.6", features = ["trace"] }
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter"] }
sha2 = "0.10"
hex = "0.4"
cargo build --release
cargo run --release
tracing 是 Rust 的结构化日志与追踪库,它把一次事件表示成「目标、级别、消息、若干字段」。tracing-subscriber 负责把这些事件输出到终端、文件或外部系统。EnvFilter 是过滤器,按目标名和级别决定哪些事件输出,通常由 RUST_LOG 环境变量控制。
下面是本文使用的初始化。它优先读 RUST_LOG,没有就用 rustdemo=info,tower_http=info;输出到 stdout,并关闭 ANSI 颜色,方便容器日志收集:
use tracing_subscriber::{layer::SubscriberExt, util::SubscriberInitExt, EnvFilter};
let filter = EnvFilter::try_from_default_env()
.unwrap_or_else(|_| EnvFilter::new("rustdemo=info,tower_http=info"));
tracing_subscriber::registry()
.with(filter)
.with(tracing_subscriber::fmt::layer().with_ansi(false))
.init();
为什么输出到 stdout,而不是自己写文件:容器和 systemd 都会接管 stdout 和 stderr,日志收集器从那里读取,自动处理轮转、归档和集中查询。应用自己写文件,要处理权限、磁盘满、轮转、多个实例写同一文件,成本高且容易丢。把日志当事件流交给平台,是更省心的做法。
结构化字段的价值在于可检索。不要把关键信息拼进消息字符串,而是作为字段:
tracing::info!(
port = config.port,
db = "sqlite",
"listening"
);
tracing::error!(
error = %error,
job_id = job_id,
"job failed"
);
这样日志系统可以按 job_id 过滤、按 error 聚合,不需要正则解析一整句中文。排查时也能直接回答「这个 job 的所有日志在哪」。字段值不要放令牌、密码、完整 SQL 或用户隐私,日志的访问范围通常比数据库大。
日志级别要有纪律。info 记录生命周期和关键业务事件,warn 记录可恢复的异常,error 记录需要人处理的问题,debug 只在本机或临时排障时开。把每个请求都打成 info,高流量下日志量会非常可观;把数据库错误打成 debug,线上又看不到。默认级别按环境配置,不要写死在代码里。
tower-http 的 TraceLayer 会自动为请求生成 span,并记录方法、路径、状态和耗时。它实际的日志字段和级别我没有在本机实测,本文只给初始化方式,不承诺具体输出格式。需要稳定格式时,用自定义中间件显式记录字段。健康检查:别只返回 200
健康检查的价值在于「让编排系统知道这个实例现在能不能工作」。只返回固定 {"status":"up"} 的接口,只能证明进程还在,不能证明它连得上数据库、拿得到配置、能写文件。数据库断了,负载均衡仍然把流量打进来,用户看到的是每个请求都 500。
就绪检查应该做一次很轻的依赖探测。SELECT 1 不查业务表、不写数据,只验证连接可用,成本很低:
use std::time::Instant;
use axum::{extract::State, http::StatusCode, Json};
use serde::Serialize;
#[derive(Serialize)]
struct Health {
status: &'static str,
db: bool,
uptime_secs: u64,
}
async fn health(State(state): State<AppState>) -> (StatusCode, Json<Health>) {
let db = sqlx::query("SELECT 1")
.fetch_one(&state.pool)
.await
.is_ok();
let code = if db {
StatusCode::OK
} else {
StatusCode::SERVICE_UNAVAILABLE
};
let status = if db { "up" } else { "degraded" };
(
code,
Json(Health {
status,
db,
uptime_secs: state.started.elapsed().as_secs(),
}),
)
}
数据库正常时的实测返回:
curl -s -i 127.0.0.1:18080/health
HTTP/1.1 200 OK
content-type: application/json
{"status":"up","db":true,"uptime_secs":0}
数据库断开时,按上面的代码应返回 503 和 {"status":"degraded","db":false,...}。这个返回没有在本机实测,因为演示工程没有故意断开数据库;代码逻辑是明确的,但上线前建议真的停一次数据库验证。
健康检查不要做得太重。不要查业务表、不要统计行数、不要调用外部支付接口;这些操作在数据库压力大时会拖慢检查,甚至把数据库压垮。也不要让健康检查依赖缓存是否命中,缓存本来就会失效,失效不等于服务不可用。判断标准是:这个依赖挂了,服务还能不能提供核心功能。
存活检查和就绪检查最好分开。存活检查只返回进程状态,失败时编排系统重启实例;就绪检查查数据库,失败时只把实例从负载均衡里摘掉,不重启。一个接口同时承担两件事,容易出现「数据库抖一下,所有实例被重启」的连锁反应。
优雅停机:别在发布时切断请求
优雅停机(graceful shutdown)是指收到停止信号后,不再接受新连接,但把已经进来的请求处理完,再退出。没有它,发布或扩容时正在处理的请求会被直接切断,用户看到连接重置或 502,后台任务也可能跑到一半消失。
Axum 0.8 的 axum::serve 提供 with_graceful_shutdown,接收一个 future;future 完成时开始停机。下面的实现同时监听 Ctrl+C 和 Unix 的 SIGTERM,Windows 上没有 SIGTERM,用 pending 占位:
use std::future::pending;
async fn shutdown_signal() {
let ctrl_c = async {
tokio::signal::ctrl_c()
.await
.expect("install ctrl-c handler");
};
#[cfg(unix)]
let terminate = async {
tokio::signal::unix::signal(
tokio::signal::unix::SignalKind::terminate(),
)
.expect("install sigterm handler")
.recv()
.await;
};
#[cfg(not(unix))]
let terminate = pending::<()>();
tokio::select! {
_ = ctrl_c => {},
_ = terminate => {},
}
tracing::info!("shutdown signal received");
}
启动部分改成:
let listener = tokio::net::TcpListener::bind(("0.0.0.0", config.port))
.await
.expect("bind port");
tracing::info!(port = config.port, "listening");
axum::serve(listener, app)
.with_graceful_shutdown(shutdown_signal())
.await
.expect("server");
这段代码在本机可以编译运行,Ctrl+C 会触发停机日志。真正部署时还要注意停止信号的传递:容器里 PID 1 必须把 SIGTERM 传给应用进程,shell 形式的入口脚本有时会吞掉信号;systemd 的 KillMode 和超时时间也要配置合理。这些运行层面的行为我没有在本机实测。
优雅停机也有上限。如果某个请求卡在慢查询上,等待它完成可能超过编排系统给的宽限期,最终还是被杀。正确做法是给请求设超时,给停机设一个最大等待时间;超过就强制退出,并接受这部分请求失败。停机不是无限等待,它只是把「立刻切断」换成「有边界地收尾」。
后台任务要单独考虑。进程内的 spawn 任务在停机时如果没有被等待,仍然会丢。可以在停机 future 里通知任务队列停止接收、等待 worker 处理完当前任务,再退出;跨进程的任务则依赖队列的确认机制。第 5 篇讲过,进程内任务本来就不保证持久化,别把优雅停机当成可靠队列的替代品。
构建与容器:release、非 root、可写目录
开发用 debug 构建,交付用 release 构建。命令是 cargo build --release,产物在 target/release/ 下。release 会开优化、去掉调试断言,编译更慢、运行更快;具体的产物体积和启动耗时我没有在本机实测,不给数字。能确认的是:不要拿 debug 二进制压测,也不要用它的启动时间判断线上冷启动。
容器部署的常见做法是两阶段构建:第一阶段用 Rust 镜像编译,第二阶段只复制二进制到精简的运行镜像。下面是一个参考 Dockerfile,镜像构建本身没有在本机实测:
FROM rust:1.99 AS builder
WORKDIR /app
COPY . .
RUN cargo build --release
FROM debian:bookworm-slim
RUN useradd -r -u 10001 app
WORKDIR /app
COPY --from=builder /app/target/release/rustdemo /usr/local/bin/rustdemo
RUN mkdir -p /data && chown app /data
USER app
ENV DATABASE_URL=sqlite:///data/app.db?mode=rwc
EXPOSE 18080
CMD ["rustdemo"]
这里有几个刻意的选择。运行镜像不装编译工具链,体积更小、攻击面更少;创建普通用户 app 并 USER app,避免进程以 root 运行;数据目录 /data 显式创建并 chown,因为 SQLite 需要写库文件、写日志文件,只读的根文件系统下必须挂一个可写卷到 /data。
只读文件系统是容器安全的常见加固项,但它和 SQLite 有直接冲突。把根文件系统设成只读后,SQLite 在 /data 里写库仍然可以,前提是 /data 是挂载的可写卷;如果 URL 指向镜像里的某个路径,第一次写入就会报「attempt to write a readonly database」。这个错误在启动时不一定出现,往往要等第一个写请求。部署前用一次真实的 POST 验证,而不是只看健康检查。
非 root 还会影响文件权限。挂载卷的属主如果和容器里的 uid 不一致,应用仍然写不进去。常见做法是显式指定运行 uid,或在启动脚本里修权限;不要在应用里用 root 兜底。权限问题应该在部署阶段解决,而不是让进程拥有过多权限。
交叉编译是另一个取舍。在 Windows 上开发、部署到 Linux,直接在 Windows 构建 Linux 二进制需要额外工具链,容易在 C 库版本上踩坑;更稳的做法是在 CI 里用和目标一致的基础镜像构建,或者用多阶段 Docker 构建把编译和运行放在同一个 Linux 环境。静态链接可以减少对系统库的依赖,但会增大体积,也会影响某些系统调用。具体选型我没有在本机实测,不在这里下结论。
时区也要统一。数据库和日志建议统一用 UTC 存储,展示时再转成本地时区;容器默认是 UTC,不要指望它和开发机一致。时间字段如果混用本地时间和 UTC,跨时区或跨夏令时就会出错,而且很难从日志里看出来。
反向代理与真实 IP
生产环境通常不会把 Axum 直接暴露到公网,而是在前面放 Nginx 或云负载均衡。代理负责 TLS 终止、静态文件、限流、超时和访问日志,Axum 只监听内网地址。这个结构带来两个必须处理的问题:真实客户端 IP 和代理头信任。
Nginx 在转发时要把原始地址写进头,应用才拿得到。关键配置是 proxy_set_header 这几行:
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
X-Real-IP 是单个地址,适合直接取;X-Forwarded-For 是逗号分隔的链,代理越多越长,取第一个还是最后一个要看信任边界。X-Forwarded-Proto 告诉应用原始请求是 HTTP 还是 HTTPS,生成跳转链接和设置 cookie 的 Secure 属性时会用到。Nginx 配置的实际运行我没有在本机实测,这里只给头名和语义。
应用侧读取这些头有一个前提:只信任来自代理的值。如果 Axum 直接暴露在公网,客户端可以自己伪造 X-Real-IP,你记录的就是假 IP。正确做法是让应用只监听内网或 localhost,由代理在边缘清除客户端传来的同名头,再写入真实值。信任链要在网络层保证,不能靠应用猜。
限流和超时也适合放在代理层。Nginx 可以按 IP 限制请求速率、限制连接数、设置读取和发送超时;应用层的限流则更了解业务维度,比如按用户、按接口。两层不冲突:代理挡住粗粒度的洪峰,应用处理细粒度的配额。具体阈值要按压测和真实流量定,不要照搬别人的数字。
TLS 在代理层终止后,应用收到的是明文 HTTP。这在本机或内网可以接受,但要确保代理到应用这一段不被外部访问;同时应用生成的绝对 URL 要用 X-Forwarded-Proto 判断协议,否则 HTTPS 页面里可能生成 HTTP 链接,被浏览器判为混合内容。
当天能自己验证的练习
- 把端口、数据库 URL、密钥全部改成环境变量读取,删掉代码里的硬编码;分别用缺
DATABASE_URL、短APP_SECRET启动,确认错误信息能指明缺什么。 - 把
RUST_LOG设为rustdemo=debug启动,观察日志量变化;再设为warn,确认info级别的启动日志消失,理解 EnvFilter。 - 停掉数据库或把 URL 改到一个不存在的文件,请求
/health,确认返回 503 和db:false;恢复后确认回到 200。 - 用 Ctrl+C 停止服务,确认打印停机日志;在停机前发一个慢请求,观察它是否被处理完再退出。
- 用只读目录启动一次,触发写接口,记录 SQLite 的报错原文;再把数据目录换成可写卷,确认写入恢复。
到这里,这条「从空目录到上线」的链路就走完了:起步、路由、数据、鉴权、任务、部署。下一篇没有固定的主题,建议回到自己的项目,把六篇里的检查表各过一遍,先让一个真实服务稳定跑起来,再考虑拆服务和加中间件。
小结
三句话收束:配置全部从环境变量来,缺失就拒绝启动,密钥不进代码和镜像;日志用 tracing 加 EnvFilter,结构化字段输出到 stdout,交给平台收集;健康检查要查数据库,优雅停机要接 with_graceful_shutdown,容器用非 root 加可写数据目录,代理层传真实 IP。
最后提醒一句:本文标注「未在本机实测」的 release 构建、Docker 镜像、systemd 与 Nginx 配置,不要直接当成已验证的结论。上线前在自己的环境里逐项跑一遍,把观察到的输出补进项目文档,那才是属于你的实测数据。