前一站:本地环境。本章说明可执行配置与边界;本次未进行公网部署、真实短信运营商联调或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被强制关闭。初始化之前准备管理员哈希,已有库重启不会根据环境变量重置管理员密码。
可以在本机使用密码哈希工具 ↗生成,密码通过标准输入读取,不放在命令行参数:
go run ./cmd/hash-password
|
终端输入需要的初始密码后回车;使用普通管道的示例会暴露在历史中,因此不推荐。若当前终端不能隐藏输入,工具明确提示;工具本身不写数据库。把输出哈希放入部署密钥配置,明文安全保存。
短信适配器契约#
应用POST JSON {phone,code} 到你控制的HTTPS适配器,Header带Authorization: Bearer <SMS_WEBHOOK_TOKEN>;适配器应验证此私有凭证,再调用真实短信供应商。返回2xx表示已接收成功,应用8秒超时、不跟随重定向。不要把此入口做成任何访客都可调用的开放短信发送器。运营商模板、额度、限额和内容审核属于适配器的实际部署责任。
Docker开发演示#
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来“解除占用”。
恢复演练#
- 保留原工作数据,不覆盖;恢复到新目录。
- 设置绝对DATABASE_PATH、UPLOAD_DIR,FRONTEND_DIR指向对应构建版本,另选端口。
- 如需保留旧会话,密钥与session快照一致;否则明确要求重新登录。
- 检查health、integrity/foreignKey、用户/笔记数量,抽查图片与私密权限。
- 用两个测试账号完成发布/评论/关注,确认新写入也可持久化。
- 记录备份时间、恢复时间和差异,再决定是否正式切换。
数据库升级与回滚#
当前只有schema版本1,未来新增迁移先在备份副本试跑。CREATE TABLE IF NOT EXISTS不自动增加既有字段。代码回滚与数据回滚不同,旧二进制不一定认识新schema;发布前写好兼容窗口与备份恢复条件。切流前做真实数据迁移演练,步骤见Java迁移。
验收:你能证明一次独立恢复,指出谁保存了上传文件、哪些密钥影响旧会话,以及数据库文件不等于完整网站备份。