# 单实例部署、Docker与备份恢复

前一站：[本地环境](local.md)。本章说明可执行配置与边界；本次未进行公网部署、真实短信运营商联调或Docker镜像运行验收，不能把教程命令当作已经在你的服务器执行过。

## 单实例部署条件

准备受支持系统、可写持久数据盘、反向代理HTTPS、域名、私有短信适配器和备份位置。先构建frontend/dist和Go二进制，运行用户只拥有程序所需权限。HTTP_ADDR绑定本机或容器内部，通过可信反向代理对外提供TLS。

生产必须设置APP_ENV=production、随机JWT_SECRET、有效ADMIN_PASSWORD_HASH、HTTPS SMS_WEBHOOK_URL和SMS_WEBHOOK_TOKEN，否则启动失败。SEED_DEMO被强制关闭。初始化之前准备管理员哈希，已有库重启不会根据环境变量重置管理员密码。

可以在本机使用[密码哈希工具](../../cmd/hash-password/main.go)生成，密码通过标准输入读取，不放在命令行参数：

```powershell
go run ./cmd/hash-password
```

终端输入需要的初始密码后回车；使用普通管道的示例会暴露在历史中，因此不推荐。若当前终端不能隐藏输入，工具明确提示；工具本身不写数据库。把输出哈希放入部署密钥配置，明文安全保存。

## 短信适配器契约

应用POST JSON `{phone,code}` 到你控制的HTTPS适配器，Header带`Authorization: Bearer <SMS_WEBHOOK_TOKEN>`；适配器应验证此私有凭证，再调用真实短信供应商。返回2xx表示已接收成功，应用8秒超时、不跟随重定向。不要把此入口做成任何访客都可调用的开放短信发送器。运营商模板、额度、限额和内容审核属于适配器的实际部署责任。

## Docker开发演示

```powershell
docker compose build
docker compose up -d
docker compose logs -f
```

compose.yaml默认development，端口只映射本机8080，两份named volume保存data/uploads。Dockerfile为Node构建、Go纯静态编译、非root运行三阶段。该compose用于本地演示，不能原封不动作为生产安全配置。

生产覆盖environment和密钥注入，关闭教学数据，配置HTTPS代理、日志轮转、资源限制和备份。不要把随机密钥写进镜像层、Git或VITE变量。多个容器不能共享同一个SQLite文件当作已验证的水平扩容方案。

## 健康和日志

health/live与ready当前都Ping数据库，只能说明连接可用，不能证明短信供应商、上传盘容量和所有业务都正常。日志使用JSON slog，可按path/error检索；开发验证码不应在production日志出现。管理维护接口执行integrity_check和foreign_key_check，只允许管理员。

请求读头5秒、读/写30秒、idle60秒，业务context20秒，关机等待10秒。反向代理超时需要与这些边界协调。上传最大20MiB，代理限制小于应用会提前拒绝，应使用清楚的413响应。

## 备份必须包含什么

数据库文件、上传目录、独立保存的JWT密钥和实际配置版本。当前开发密钥位于data/.jwt-secret；生产密钥通常来自部署密钥系统。用户资料与文件相互引用，只有数据库没有uploads会产生坏图。

最容易理解的首次备份方式是停机：Ctrl+C正常停止，确认进程退出，再复制完整data和uploads到一个新目录。不要在运行时只复制xiaolanshu.db而漏掉WAL。在线备份应使用SQLite backup API或经过验证的VACUUM INTO流程，不自己删-wal/-shm来“解除占用”。

## 恢复演练

1. 保留原工作数据，不覆盖；恢复到新目录。
2. 设置绝对DATABASE_PATH、UPLOAD_DIR，FRONTEND_DIR指向对应构建版本，另选端口。
3. 如需保留旧会话，密钥与session快照一致；否则明确要求重新登录。
4. 检查health、integrity/foreignKey、用户/笔记数量，抽查图片与私密权限。
5. 用两个测试账号完成发布/评论/关注，确认新写入也可持久化。
6. 记录备份时间、恢复时间和差异，再决定是否正式切换。

## 数据库升级与回滚

当前只有schema版本1，未来新增迁移先在备份副本试跑。CREATE TABLE IF NOT EXISTS不自动增加既有字段。代码回滚与数据回滚不同，旧二进制不一定认识新schema；发布前写好兼容窗口与备份恢复条件。切流前做真实数据迁移演练，步骤见[Java迁移](../02-architecture/migration.md)。

验收：你能证明一次独立恢复，指出谁保存了上传文件、哪些密钥影响旧会话，以及数据库文件不等于完整网站备份。
