第五章：部署监控与持续迭代 — 从单次修复到可维护体系

部署路径管理

服务器上存在两套代码目录，这是一个容易踩的坑：

目录	用途
/opt/english-api/	生产环境，systemd 服务 WorkingDirectory
/root/workspace/english-api/	开发副本，用于调试和测试

关键规则：systemd 管理的生产服务只读 /opt 下的代码。在 /root/workspace 下改了代码不生效，是因为改错目录了。部署更新时，需要把改动同步到 /opt 下，清缓存，再重启服务。

另外，路由文件的位置也有讲究——生产环境的路由直接放在 /opt/english-api/routers/ 下，不是在 server/ 子目录里。这和本地 git 仓库的结构不一样，第一次部署时很容易搞混。

Python 缓存陷阱

改完 .py 文件后重启服务，发现修改没生效——这是 Python 的 __pycache__ 在作怪。旧的 .pyc 字节码缓存被继续使用，新的源码被忽略了。

# 每次部署的标准操作
find /opt/english-api -name '__pycache__' -type d -exec rm -rf {} +
systemctl restart english-api

把这个操作写进部署脚本，避免”改了代码但不生效”的诡异现象。

systemd 服务管理

后端通过 systemd 管理，服务名 english-api。几个常用操作：

systemctl status english-api    # 查看状态
systemctl restart english-api   # 重启（改完代码后）
journalctl -u english-api -f    # 实时日志

# 偶尔遇到旧进程占端口的情况
ss -tlnp | grep 8000           # 查看谁在占 8000 端口
fuser -k 8000/tcp              # 强制释放端口
systemctl restart english-api  # 再重启

注意区分：systemctl restart 和手动 python -m uvicorn 是两个独立进程。手动启动的 uvicorn 不受 systemd 管理，kill 不掉会导致端口冲突。

前端构建与验证

前端每次改动要过两道验证：

cd frontend
npx tsc --noEmit          # TypeScript 类型检查
npm run build:weapp        # 生产构建

两个都通过才算合格。开发时用 npm run dev:weapp 进入 watch 模式，配合微信开发者工具实时预览。

接口监控

经历了 STT 卡死整个 API 的教训后，建立了简单的持续检查机制。每次改动部署后，手动验证四个核心接口：

接口	验证方式
/api/health	curl 检查返回 {"status":"ok"}
/api/stt	用 TTS 生成的标准英文语音测试转写准确性
/api/tts	发送 500 字符英文文本，检查返回音频大小 > 100KB
/api/chat/send	发送一条对话消息，检查 AI 正常回复

Git 分支规范

项目采用双分支策略，简单但有效：

• 功能类改动（逻辑修复、API、store、hooks、工具函数）→ 推送到 master
• UI 类改动（样式、布局、颜色、间距、视觉调整）→ 推送到 ui_change

判断规则很简单：改 .scss/.wxss/.css 或组件内联样式就是 UI，改业务逻辑就是功能。混合改动时按主要目的判断，紧密耦合就拆成两次提交分别推送。

WordPress 博客环境

服务器上还跑着一个 WordPress 个人博客（就是你正在读的这篇文章所在的地方），技术细节：

• Nginx 监听 127.0.0.1:8080，仅本地环回，不对外暴露
• PHP-FPM 通过 unix socket (/run/php-fpm/www.sock) 处理 PHP
• WordPress 文件在 /root/workspace/wordpress/
• 数据库和 CleanLearn 共用同一台 MariaDB，库名 wordpress
• 对外通过 Nginx 反向代理暴露（admintest.xiaoyinxia.com）

后续计划

• HTTPS 证书：当前 API 走 HTTP，真机访问时微信会拦截。需要给 admintest.xiaoyinxia.com 配置 SSL 证书
• 自动化部署脚本：把”同步代码 → 清缓存 → 重启服务 → 验证接口”串成一个脚本，一键完成
• 接口监控自动化：用 cron 定时跑四个接口的健康检查，失败时告警
• 前端 CI：每次 push 自动跑 tsc --noEmit + build:weapp

← 返回目录