适用场景与部署思路

Camelot 常用于从 PDF 文件中提取表格数据，适合处理发片明细、实验记录、业务报表、设备清单、统计表等结构化资料。个人版部署的核心目标不是做一个复杂平台，而是把本地可运行的表格识别能力封装成稳定的服务：用户上传 PDF，服务调用 Camelot 解析指定页码，返回 JSON 或 CSV 文件路径，便于后续接入自动化流程、知识库整理或数据清洗任务。

生产环境部署要重点关注四件事：第一，系统依赖必须完整，否则 lattice 模式容易解析失败；第二，Python 环境要隔离，避免和其他项目包版本冲突；第三，API 服务要有基础鉴权、文件大小限制和日志记录；第四，调用测试不能只看服务是否启动，还要验证 PDF 上传、页码选择、异常返回和结果导出是否正常。

环境准备与版本建议

建议使用 Ubuntu 22.04 LTS 或 Debian 12 作为服务系统，Python 版本建议为 3.10 或 3.11。服务器配置不需要很高，个人使用 2 核 CPU、4GB 内存即可起步；如果 PDF 页数多、表格线复杂或并发较高，建议提升到 4 核 8GB，并为上传目录和结果目录预留足够磁盘空间。

部署前先更新系统组件，可执行：sudo apt update && sudo apt upgrade -y。随后安装基础工具：sudo apt install -y python3 python3-venv python3-pip build-essential ghostscript libgl1 libglib2.0-0。ghostscript 对 Camelot 的 lattice 解析很关键，libgl1 和 libglib2.0-0 常用于解决 OpenCV 相关运行错误。若系统没有字体包，部分 PDF 预览或转换可能异常，可补充安装常用字体组件。

创建目录与安装 Camelot

建议将服务目录放在 /opt/camelot-api，数据目录单独管理。例如执行：sudo mkdir -p /opt/camelot-api/uploads /opt/camelot-api/outputs /opt/camelot-api/logs，并将目录授权给实际运行服务的普通用户。不要直接使用高权限账号长期运行 API 服务，这会放大误操作和文件写入风险。

进入项目目录后创建虚拟环境：python3 -m venv .venv，然后启用环境：source .venv/bin/activate。升级安装工具：pip install --upgrade pip setuptools wheel。安装 Camelot 与 API 所需组件：pip install "camelot-py[cv]" fastapi uvicorn python-multipart pandas。安装完成后执行 python -c "import camelot; print(camelot.__version__)"，能正常输出版本号说明核心包已可导入。

如果导入时报 cv2、glib 或 ghostscript 相关错误，通常是系统依赖缺失。先确认 gs -version 是否有输出；再检查 OpenCV 依赖是否安装完整。不要一开始就盲目降级所有 Python 包，应先定位报错来源，再处理对应依赖。

封装 API 服务的关键配置

个人版服务可使用 FastAPI 封装三个接口：健康检查、PDF 上传解析、结果下载。健康检查接口用于进程监控；解析接口接收 PDF 文件、页码参数、解析模式参数；结果接口返回生成的 CSV 或 JSON 文件。解析模式一般分为 lattice 和 stream：前者适合有清晰表格线的 PDF，后者适合没有线框但文本排列规整的表格。实际部署时可允许调用方传入 mode 参数，但要设置默认值和白名单校验。

API配置建议写入环境变量或单独配置文件，至少包括：服务端口、上传文件最大体积、结果保存天数、访问令牌、日志级别、默认解析页码。访问令牌不应硬编码在接口说明页或前端页面里；个人使用也建议开启简单校验，例如请求头携带 X-API-Key，服务端比对后才允许解析。文件名要做安全处理，避免直接使用用户上传的原始文件名作为保存路径。

启动调试可执行：uvicorn app:app --host 0.0.0.0 --port 8000。确认无误后再交给进程管理工具运行。生产环境不要长期依赖终端窗口启动，否则会因为会话关闭导致服务中断。

生产环境进程管理

建议使用 systemd 托管服务。服务配置中指定 WorkingDirectory 为 /opt/camelot-api，ExecStart 指向虚拟环境中的 uvicorn，并设置普通用户运行。还应配置 Restart=always，让服务异常退出后自动拉起。修改配置后执行 sudo systemctl daemon-reload，再执行 sudo systemctl enable camelot-api 和 sudo systemctl start camelot-api。查看状态可用 sudo systemctl status camelot-api，实时日志可用 journalctl -u camelot-api -f。

如需对外提供访问，建议在前面放置反向袋里，只开放必要端口，并限制上传体积与请求频率。个人版不建议承载大量并发任务，因为 Camelot 解析 PDF 属于较耗 CPU 的操作，多个大文件同时处理会明显增加延迟。更稳妥的做法是使用任务队列或限制同一时间的解析数量。

API 调用测试步骤

第一步，测试健康检查。执行 curl https://127.0.0.1:8000/health，正常应返回服务状态、版本号或时间戳。若本机可访问但外部不可访问，需要检查监听地址、端口放行和反向袋里配置。

第二步，准备一份表格清晰、页数较少的 PDF，先用本地命令测试 Camelot 能否解析。例如进入虚拟环境后，用 Python 简单调用 camelot.read_pdf("sample.pdf", pages="1", fla vor="lattice")。若能得到 tables 数量，再进行 API 测试；如果本地调用都失败，说明问题不在接口层，应先处理 PDF 类型或依赖问题。

第三步，测试上传解析接口。可使用 curl 发起 multipart 请求，传入 file、pages、mode 等参数，并在请求头加入 X-API-Key。返回结果应包含任务编号、识别到的表格数量、输出文件名或数据预览。建议分别测试 pages=1、pages=1-3、pages=all，以及 mode=lattice、mode=stream 两种模式，观察结果差异。

第四步，测试异常场景。上传非 PDF 文件、空文件、超大文件、错误页码、错误令牌，接口都应返回清晰错误信息，而不是直接暴露程序堆栈。生产环境中，错误信息要能帮助用户修正参数，但不应暴露服务器目录、内部变量和完整依赖路径。

常见问题与处理办法

问题一：解析结果为空。优先确认 PDF 是否为扫描图片型文件。Camelot 主要处理可选中文本的 PDF，如果页面只是图片，需要先做文字识别流程，再考虑表格结构化。其次尝试在 lattice 与 stream 之间切换，并指定正确页码。

问题二：表格列错位。可调整 Camelot 的参数，如 table_areas、columns、strip_text 等。对于版式固定的报表，建议为不同模板保存专用参数，不要只依赖默认解析。

问题三：服务启动正常但上传失败。检查 python-multipart 是否安装，上传目录是否有写入权限，反向袋里是否限制了请求体大小。还要确认临时目录空间是否充足，大 PDF 在处理过程中会产生中间文件。

问题四：线上偶发超时。可限制单次上传页数，或把解析任务改为异步：接口先返回任务编号，后台处理完成后再查询结果。个人版场景下，先做页数限制通常最简单有效。

安全边界与维护建议

不要把 Camelot API 设计成无验证的公开上传服务。即使是个人工具，也应设置访问令牌、文件体积上限、文件类型校验、结果定期清理和日志轮转。上传文件可能包含合同、客户资料或内部数据，建议只保留必要时间，并避免把原始文件同步到不受控位置。

升级前先记录当前版本：pip freeze > requirements.lock，并保留一份可用的配置文件。升级可在测试目录重新创建虚拟环境验证，确认同一批 PDF 的解析结果没有明显变化后，再替换生产环境。若升级后出现解析差异，可通过 requirements.lock 回退到旧版本。稳定性比盲目追新更重要，尤其是已经接入自动化流程时。

完成以上步骤后，个人版 Camelot 就具备了可持续运行的基础能力：依赖清晰、服务可守护、接口可测试、异常可追踪。后续可以继续增加模板参数管理、批量任务、结果预览和权限分组，但核心原则不变：先保证解析准确与服务稳定，再扩展更多功能。