前五篇的工程在本地跑得很好,第一次放到服务器就遇到一串问题。端口 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 只读不会在启动时报,往往是第一次写入才爆。两者都属于「配置看起来对,运行时才发现环境不对」,只能靠启动自检和真实请求覆盖。

健康检查分两种:存活检查(liveness)只回答「进程还在不在」,不该依赖数据库;就绪检查(readiness)回答「现在能不能接流量」,应该查数据库和关键依赖。把两者混成一个接口,数据库抖动时可能把所有实例都重启掉,反而放大故障。

配置:全部从环境变量来

配置的第一条纪律是「代码里不写死环境相关的东西」。端口、数据库地址、签名密钥、日志级别、外部服务地址,都应该在启动时从环境变量读取,代码只提供默认值或直接报错。这样同一份二进制可以在本机、测试、生产运行,不需要为每个环境重新编译。

下面的 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 链接,被浏览器判为混合内容。

当天能自己验证的练习

  1. 把端口、数据库 URL、密钥全部改成环境变量读取,删掉代码里的硬编码;分别用缺 DATABASE_URL、短 APP_SECRET 启动,确认错误信息能指明缺什么。
  2. 把 RUST_LOG 设为 rustdemo=debug 启动,观察日志量变化;再设为 warn,确认 info 级别的启动日志消失,理解 EnvFilter。
  3. 停掉数据库或把 URL 改到一个不存在的文件,请求 /health,确认返回 503 和 db:false;恢复后确认回到 200。
  4. 用 Ctrl+C 停止服务,确认打印停机日志;在停机前发一个慢请求,观察它是否被处理完再退出。
  5. 用只读目录启动一次,触发写接口,记录 SQLite 的报错原文;再把数据目录换成可写卷,确认写入恢复。

到这里,这条「从空目录到上线」的链路就走完了:起步、路由、数据、鉴权、任务、部署。下一篇没有固定的主题,建议回到自己的项目,把六篇里的检查表各过一遍,先让一个真实服务稳定跑起来,再考虑拆服务和加中间件。

小结

三句话收束:配置全部从环境变量来,缺失就拒绝启动,密钥不进代码和镜像;日志用 tracing 加 EnvFilter,结构化字段输出到 stdout,交给平台收集;健康检查要查数据库,优雅停机要接 with_graceful_shutdown,容器用非 root 加可写数据目录,代理层传真实 IP。

最后提醒一句:本文标注「未在本机实测」的 release 构建、Docker 镜像、systemd 与 Nginx 配置,不要直接当成已验证的结论。上线前在自己的环境里逐项跑一遍,把观察到的输出补进项目文档,那才是属于你的实测数据。