4.6 KiB

Raw Blame History

HappyWedding 生产运维说明

本文档对应 HappyWedding（hw）在 Linux 主机上以 Caddy + systemd + Gunicorn 方式运行时的日常运维操作。

1. 服务组成

线上服务主要由以下部分组成：

caddy
- 对外提供 HTTP/HTTPS
- 反向代理到 127.0.0.1:8000
hw.service
- 由 systemd 托管
- 启动 Gunicorn
- Gunicorn 载入 run:app
数据库
- 推荐 MySQL
- 连接串由 /etc/hw/hw.env 中的 DATABASE_URL 控制

2. 日常查看命令

2.1 查看应用服务状态

sudo systemctl status hw --no-pager

2.2 查看应用日志

sudo journalctl -u hw -f

2.3 查看 Caddy 日志

sudo journalctl -u caddy -f

2.4 查看健康检查

curl -fsS http://127.0.0.1/health

如果走域名验证：

curl -fsS https://your-domain/health

3. 常规发布流程

假设你已经把最新代码同步到 /opt/hw：

cd /opt/hw
sudo bash scripts/deploy-systemd.sh
sudo bash scripts/verify-deployment.sh

建议的发布后检查：

systemctl status hw --no-pager
journalctl -u hw -n 100 --no-pager
curl -fsS https://your-domain/health
打开浏览器访问首页和登录页

4. 首次初始化基础数据

仅在数据库是全新空库时执行：

cd /opt/hw
sudo RUN_SEED_ALL=1 bash scripts/deploy-systemd.sh

已有生产数据时，不要重复无脑执行 seed-all，虽然项目当前多数 seed 命令偏幂等，但生产环境仍应谨慎。

5. 修改环境变量后的操作

如果你修改了 /etc/hw/hw.env，需要重启服务让其生效：

sudo systemctl restart hw
sudo bash /opt/hw/scripts/verify-deployment.sh

6. Caddy 配置变更

修改 Caddy 配置后建议：

sudo systemctl reload caddy

若怀疑配置有问题，可先查看：

sudo systemctl status caddy --no-pager
sudo journalctl -u caddy -n 100 --no-pager

7. 回滚建议

当前仓库未内置自动回滚脚本，建议按以下原则手工回滚：

保留最近一个稳定版本代码目录或 git tag
回滚代码到稳定版本
重新执行：

sudo bash scripts/deploy-systemd.sh
sudo bash scripts/verify-deployment.sh

如果本次发布包含数据库迁移：

优先评估迁移是否可逆
若不可逆，不要直接回滚旧代码后忽略数据库兼容性
生产环境务必先做数据库备份

8. 备份建议

8.1 MySQL

建议至少定期做：

mysqldump --single-transaction --quick --default-character-set=utf8mb4 -u <user> -p <database> > hw-backup.sql

8.2 SQLite（仅轻量环境）

停止服务后备份：

sudo systemctl stop hw
cp /opt/hw/instance/happywedding.db /opt/hw/instance/happywedding.db.bak
sudo systemctl start hw

9. 常见故障排查

9.1 `hw.service` 启动失败

先看：

sudo systemctl status hw --no-pager
sudo journalctl -u hw -n 200 --no-pager

优先检查：

/etc/hw/hw.env 是否存在
HW_SECRET_KEY 是否仍是占位值
DATABASE_URL 是否为空或格式错误
/opt/hw/.venv 是否存在
Gunicorn 是否已安装到虚拟环境中

9.2 验证脚本失败：端口未监听

说明 Gunicorn 没有在 127.0.0.1:8000 正常起来。检查：

sudo journalctl -u hw -n 200 --no-pager

9.3 `/health` 不通

可能原因：

hw.service 没起来
Caddy 没 reload 成功
域名未正确指向主机
防火墙未放行 80/443

9.4 CSV 相关功能异常

优先检查目录权限：

/opt/hw/instance
/opt/hw/instance/csv_previews

它们需要对运行用户 hw 可写。

10. 安全提醒

生产环境不要使用默认 HW_SECRET_KEY
/etc/hw/hw.env 应限制读取权限
Gunicorn 仅监听本机，不要直接暴露到公网
当前项目仍建议在正式发布前补充 CSRF
如果主机是内网 / 离线环境，需要确保发布包中已经包含编译后的 app/static/css/main.css，或确保部署流程可在主机上执行 npm run build:css

10.1 前端样式构建提醒

当前生产样式不再依赖 CDN，而是依赖 Tailwind CLI 编译产物。

如发布包含样式改动，建议在 /opt/hw 下额外确认：

cd /opt/hw
npm install
npm run build:css

然后再执行：

sudo bash scripts/deploy-systemd.sh

11. 建议保留的最小操作清单

建议把以下命令记录到你的运维笔记中：

sudo systemctl status hw --no-pager
sudo systemctl restart hw
sudo journalctl -u hw -f
sudo journalctl -u caddy -f
sudo bash /opt/hw/scripts/verify-deployment.sh
curl -fsS https://your-domain/health

4.6 KiB Raw Blame History