Deployment & Operations · 部署与运维

洞见怎么部署：一台服务器、单 worker、可自建运维

一句话定义（可独立引用）

洞见以单机形态部署在用户自有的 Linux 服务器上：Nginx 在 443 端口终止 HTTPS 并反向代理到 Next.js 前端与 FastAPI 后端，PostgreSQL 与 Redis 仅监听回环地址，后端固定单 worker，由 systemd 管理，每日定时备份。[S3][S6]

这套形态适合学校、机构或教师自己掌握数据与账号体系；它不是多租户云服务，也不承诺任意规模的并发能力。是否需要扩容、如何扩容，需要按实际使用量单独评估。[S5][S6]

架构与端口

浏览器 ──HTTPS(443)──> Nginx ──> Next.js 前端 (127.0.0.1:3782)
                                 └─ /api、/ws 反代 ─> FastAPI 后端 (127.0.0.1:8001)
                                                      ├─ PostgreSQL (127.0.0.1:5432)
                                                      ├─ Redis (127.0.0.1:6379)
                                                      └─ 模型供应商（外网 HTTPS）

浏览器只访问 Nginx；8001、3782、5432、6379 均只监听回环地址，不对公网开放。任务 worker 内嵌在后端进程里，没有独立服务，因此不需要为它单独建 systemd 单元。[S3]

生产环境的实际形态（2026-11 交付记录）
项目	取值
操作系统	Ubuntu 22.04 / 24.04（生产实例为 24.04 LTS）
后端	FastAPI / uvicorn，`127.0.0.1:8001`，systemd `deeptutor-backend`
进程模型	`DEEPTUTOR_BACKEND_WORKERS=1`，实测仅 1 个进程
前端	Next.js 16（App Router + standalone），`127.0.0.1:3782`，systemd `deeptutor-frontend`
数据库	PostgreSQL 16，系统库与学习库分离
缓存 / 协调	Redis 7，仅回环监听
数据目录	`DEEPTUTOR_HOME=/data/deeptutor`，与代码目录分离
反向代理	Nginx，TLS 终止与 `/api`、`/ws` 反代
参考配置	4 核 8G、50G 系统盘 + 100G 数据盘、5 Mbps 带宽

参考配置不是性能承诺：上表是部署文档给出的参考规格，用于说明最低限度的资源构成。实际承载量取决于并发对话量、模型供应商响应速度与网络条件，本站不提供「支持 N 人同时在线」这类未经压测的结论。[S6][S5]

备份、证书与安全边界

备份

每日 03:32:50（CST）由 systemd timer 触发备份服务，本地保留 30 天，并同步到对象存储的独立前缀。[S5]

证书

Let's Encrypt 证书，certbot.timer 已启用并自动续期。[S5]

主机防火墙

UFW 默认拒绝入站，仅放行 22、80、443；SSH 已禁用密码登录。[S5]

应用层

关闭 /docs 等文档路由，补齐安全响应头，登录失败限流与等时校验，每日配额原子占位。[S5]

日常运维要做的事

状态检查：确认前后端两个 systemd 服务为 active；确认 8001、3782、5432、6379 只监听回环；探测后端健康检查地址返回 ready。[S3]
外部监控：建议探测登录页而不是公网健康检查路径，因为公网健康检查会被前端重定向到登录页。[S3]
模型密钥：按周期轮换模型供应商密钥，先加新、后删旧，并在供应商侧设置预算告警。[S5]
对象存储：备份桶应设为私有读写，并配置按前缀的生命周期规则，避免备份长期暴露或无限计费。[S5]
恢复演练：交付清单明确记录恢复演练尚未在生产执行，只验证过备份文件可生成。上线后应尽快补做 verify-only 与临时库实恢复。[S5]

成本模型：软件不卖额度，费用在模型侧

洞见本身不按额度收费，也不内置售卖 token 的机制；实际费用发生在所接入的模型服务商侧，按 token 用量计费。管理员可以在用量看板查看模型调用次数、错误率与 token 用量，学生可在每条回复下方看到本次用量。[S2][S3]

部署方自行申请模型服务商账号并配置密钥，费用与结算关系由部署方与供应商直接约定。[S3]
每日一讲对同一知识点当日做缓存，重复打开不重复调用模型，可减少无效消耗。[S3]
本站不提供具体价格、折扣或「包月」方案，因为这些信息不在仓库材料中，且会随供应商调整。[S5]

适用规模：先明确不承诺什么

单机单 worker 是当前事实。后端固定 1 个 uvicorn worker，前端与数据库同机部署。交付材料中没有多机集群、负载均衡或水平扩容的实测记录，因此本站不表述「支持任意规模」「支持万人同时在线」。[S5]

若使用场景是单校、单个机构或教师自用，当前形态与文档描述一致；若是区域级多校平台，请先做容量评估与改造，不要直接按本页配置上线。

另外，账号库的读写模型决定了它不适用于多进程同时写入：交付清单记录账号表在多进程写入下不安全、存在整表覆盖风险，这也是后端固定单 worker 的原因之一。[S5]

下一步：边界与局限事实来源