打包服务,检查重启与故障
整理启动方式与数据目录,用Docker打包,并沿请求链定位常见故障。
部署就是把程序、依赖与配置放到一个持续运行的环境中。现在我们已经有服务文件和数据库,接下来把启动方式固定下来,并确认服务停止后数据仍然可用。
先在本机跑通这条流程,再迁移到服务器。这个练习的两枚演示令牌适合本地观察团队隔离;对外上线前应换成真实账号体系签发的凭据,并加入HTTPS、限流与访问控制。
整理项目结构
完成前五节后,主要文件如下:
agentdepth-kb/
requirements.txt
storage.py
models.py
provider.py
main.py
seed.py
evaluate.py
tests/
test_api.py
data/
kb.sqlite3hello.py、storage_check.py、search_demo.py和 request_demo.py 是前面使用的练习脚本,也可以保留。服务运行的核心是main、models、provider和storage。
先完成本机重启检查
启动服务,查询一次住宿制度。按Ctrl+C停止,再使用原命令启动,重新查询。资料来自 data/kb.sqlite3,服务重启后仍能找到。
如果重启后资料为空,先检查 KB_DB_PATH 是否指向另一份文件。确认路径比重新导入更重要,否则容易把“读错数据库”误当成“数据丢失”。
使用Docker打包
先确认 docker version 能显示客户端和服务端信息。保存为 Dockerfile:
FROM python:3.13.15-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY *.py ./
ENV KB_DB_PATH=/app/data/kb.sqlite3
EXPOSE 8010
CMD ["python", "-m", "uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8010"]保存为 .dockerignore,缩小构建上下文:
.venv
__pycache__
.pytest_cache
data
.env*
.git镜像保存程序和依赖;容器是镜像运行起来的进程;数据卷独立保存数据库。这里使用命名卷,Windows与macOS命令一致。
在项目根目录执行:
docker build -t agentdepth-kb:local .
docker volume create agentdepth-kb-data
docker run --rm -v agentdepth-kb-data:/app/data agentdepth-kb:local python seed.py
docker run --rm --name agentdepth-kb -p 127.0.0.1:8010:8010 -v agentdepth-kb-data:/app/data agentdepth-kb:local如果本机的Uvicorn还占着8010端口,先停止它。容器启动后,用浏览器打开 http://127.0.0.1:8010/docs,继续使用第四节的身份和请求。
在另一个终端查看日志、停止服务:
docker logs agentdepth-kb
docker stop agentdepth-kb再次执行最后一条 docker run 启动命令,查询住宿资料。即使容器被删除,挂载的命名卷仍保留数据库。操作系统为Docker提供的实际资源与网络条件,都会影响构建和运行时间。
沿请求链定位故障
| 现象 | 检查顺序 | 修复后怎么确认 |
|---|---|---|
| 无法连接 | 服务进程、端口、容器映射 | 先请求/health,再请求/ask |
| 401 | 当前请求是否带正确令牌 | 用已知alpha令牌重试 |
| 422 | 错误响应指向哪个字段 | 改为 {"query":"住宿"} 重试 |
| 查不到资料 | 数据库路径、是否导入、团队、切词 | 先精确词,再换一种措辞 |
| 502 | 模型地址、网络、凭据、模型名与超时 | 先恢复摘录模式,再单独检查模型连接 |
| database locked | 是否有另一个进程长时间写库 | 结束自己未提交的事务,缩短事务后重试 |
当前SQLite方案适合单机学习和小规模原型。访问量增加后,用真实负载测量写入等待和尾部延迟,再决定是否迁移服务型数据库、增加队列或独立检索服务。
把这个项目讲清楚
可以按一次请求介绍项目:输入先校验身份和格式,按团队检索资料,返回摘录或生成回答,再检查引用。随后展示更新、删除、跨团队访问和没有依据这四种情况。
当前版本已经跑通真实HTTP、SQLite持久化、全文检索、引用与评测。接下来值得增加的是实际文档解析、Embedding、重排与聊天界面;逐项加入后,用第五节的固定问题比较收益。框架Agent与性能优化会形成后续项目。
课后练习展开习题收起习题
独立任务:迁移服务端口
保持代码不变,把本机访问端口改为8011,运行请求脚本并查看健康接口。写下改了哪一条命令、哪一处请求地址。
参考结果
容器内部仍为8010,映射参数改为 -p 127.0.0.1:8011:8010;请求脚本base改为 http://127.0.0.1:8011。这样就把外部访问地址和容器内部监听地址区分开了。
容器持久数据的用法见 Docker数据卷文档。