生产部署

构建

pnpm install --frozen-lockfile
pnpm build:web
cargo build --bin yufu --features webui --release

产物为单个二进制 target/release/yufu，前端已嵌入。部署时只需要二进制、配置文件、 RSA 私钥与数据库。

生产配置要点

oidc.issuer 必须是公开 HTTPS 基址，且与浏览器访问地址完全一致。
auth.secret 使用足够长的随机值，并与其他环境隔离。
oidc.rsa_private_key_path 指向持久化私钥；生产不会自动生成。
不要启用 --allow-insecure-loopback-cookies。
security_clock.servers 使用受信网络内的 NTP 来源。
数据库使用独立账号与强密码，限制来源网段。

systemd

安装目录约定以安装包附带的 conf/yufu.service 为准：

[Unit]
Description=Yufu User & Auth Service (yufu)
Requires=network-online.target
After=network-online.target

[Service]
Type=simple
DynamicUser=yes
ExecStart=/usr/bin/yufu --config /etc/yufu/yufu.toml
WorkingDirectory=/var/lib/yufu
StateDirectory=yufu
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target

sudo install -m 0755 yufu /usr/bin/yufu
sudo install -d -m 0755 /etc/yufu
# 安装已经编辑完成的配置，不要直接启用示例
sudo install -m 0640 yufu.toml /etc/yufu/yufu.toml
sudo install -m 0644 yufu.service /etc/systemd/system/yufu.service
sudo systemctl daemon-reload
sudo systemctl enable --now yufu
sudo systemctl status yufu

服务以 DynamicUser=yes 运行，没有固定账户或 UID：配置文件的读取权限需通过补充组（例如 drop-in 中设置 SupplementaryGroups=）或 ACL 授予；签名私钥建议放在 /var/lib/yufu/ 下，该目录由 StateDirectory=yufu 管理。Windows 与 macOS 安装包只提供手动运行的可执行文件，不含服务注册。

反向代理

server {
    listen 443 ssl http2;
    server_name id.example.com;

    ssl_certificate     /etc/ssl/id.example.com.pem;
    ssl_certificate_key /etc/ssl/id.example.com.key;

    location / {
        proxy_pass http://127.0.0.1:4000;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

代理必须保留原始 Host 与协议信息，否则 Cookie 与 Origin 校验会失败。

健康检查

curl -fsS https://id.example.com/api/v1/health/ready

返回 200 且 security_clock_synchronized=true 才应接入流量。时钟异常时认证入口返回 503，这是预期行为，不要通过重试绕过。

升级

备份数据库与 RSA 私钥。
构建新版本二进制与前端。
停止服务，替换二进制。
启动服务，自动执行版本化迁移。
验证 Discovery、健康检查与一次真实登录。

回滚边界

数据库迁移是版本化的。回滚二进制前必须确认新版本没有执行不可逆迁移；已有库的历史数据、已注册客户端与授权不会自动删除，回滚不会恢复被撤销的会话。

容器部署

偏好容器编排时不必自行拼装：仓库提供 deploy/docker 参考栈，由 PostgreSQL、身份服务与 Caddy TLS 入口组成，步骤见容器部署。容器内的服务只能监听 0.0.0.0，因此不能用 --allow-insecure-loopback-cookies，对外入口必须是 HTTPS。