部署前先弄清它解决什么问题

Zotero AI 通常指围绕 Zotero 文献管理流程扩展出的智能辅助服务。常见能力包括论文摘要提取、问答检索、笔记整理、标签建议、PDF 内容解析与向量索引等。

使用 Docker 部署的好处是：环境隔离、迁移方便、升级可控。不必在系统里反复安装运行库。适合个人研究者、实验室小团队、知识库维护人员，以及需要在固定设备上长期运行文献辅助服务的用户。

需要注意的是，不同开源项目对“Zotero AI”的实现方式并不完全相同：有的提供 Web 界面，有的作为 API 服务供插件调用，有的需要连接本地 Zotero 数据库或导出的文献目录。

部署前应确认项目文档中的镜像名称、端口、环境变量和数据目录要求。下面以通用 Docker 思路讲解，命令中的镜像地址、容器名和变量名可按实际项目替换。

准备条件与目录规划

准备条件：建议准备一台已安装 Docker 的电脑或服务器，系统可以是 Linux、macOS 或 Windows。Windows 用户建议使用 Docker Desktop，并确认文件共享目录已开启。设备需要能访问镜像仓库，也需要能访问你所选择的模型接口或本地模型服务。

若要处理大量 PDF，建议至少预留 4GB 以上内存和足够磁盘空间，索引文件会随着文献数量增长。

目录规划：推荐新建一个独立工作目录，例如 /opt/zotero-ai，下面再分出三类目录：

• data：用于保存索引、缓存、上传文件或数据库
• config：用于存放配置文件
• logs：用于排查启动和调用错误

这样做的好处是：容器删除或重建后，关键数据仍然保留。后续迁移也只需要复制这个目录。

镜像拉取与版本选择

如果项目提供了正式镜像，可以先执行拉取命令，例如 docker pull ghcr.io/example/zotero-ai:latest。其中 ghcr.io/example/zotero-ai:latest 只是示例，实际应替换为项目页面给出的镜像。

版本选择：初次部署不建议盲目追求最新标签。生产使用更推荐固定版本号，例如 :1.2.0，这样在后续排查问题时更容易复现环境。

拉取完成后可通过 docker images 查看镜像是否存在。若拉取速度慢或失败，先检查镜像地址、标签是否拼写正确，再检查 Docker 是否正常登录对应仓库。

不要从来源不明的位置下载二次打包镜像，尤其是需要填写模型密钥、文献内容和个人资料的工具，镜像可信度直接关系到数据安全。

使用 docker run 快速启动

最简单的启动方式是使用 docker run。示例命令：

docker run -d --name zotero-ai -p 8080:3000 -v /opt/zotero-ai/data:/app/data -v /opt/zotero-ai/config:/app/config -e TZ=Asia/Shanghai -e AI_PROVIDER=openai_compatible -e AI_API_KEY=你的密钥 --restart unless-stopped ghcr.io/example/zotero-ai:1.2.0

参数说明：-d 表示后台运行，--name 指定容器名，-p 负责端口映射，-v 负责目录挂载，-e 用来传入环境变量。

端口映射：8080:3000 表示宿主机的 8080 端口映射到容器内部的 3000 端口。用户访问时使用宿主机地址加 8080，而不是容器内部端口。如果本机已有服务占用 8080，可以改成 18080:3000。容器内部端口通常由项目固定，除非文档允许修改，否则不要随意改右侧端口。

推荐使用 compose 管理配置

长期使用更建议采用 Docker Compose。把启动参数写成配置文件，减少手输命令导致的错误。

在工作目录中创建 compose.yml，配置内容包含服务名、镜像、端口、目录挂载、环境变量和重启策略。虽然不同项目字段略有差异，但核心思路一致：

• 把会变化的密钥、模型地址、数据路径集中管理
• 把容器内部数据路径挂载到宿主机固定目录

常用命令：

• 启动：docker compose up -d
• 查看状态：docker compose ps
• 查看日志：docker compose logs -f

如果修改了环境变量或端口，执行 docker compose down 后再 docker compose up -d。只要数据目录没有删除，重建容器不会清空索引和配置。

数据目录配置的关键细节

数据目录是部署中最容易被忽视的部分。很多用户只关注服务能否打开，却把数据保存在容器内部，结果容器升级或删除后索引全部丢失。

必须挂载的路径：凡是项目文档标明的 /app/data、/data、/config、/uploads 等路径，都应优先考虑挂载到宿主机。若项目使用 SQLite、向量库或缓存文件，尤其要保证挂载目录具备读写权限。

Linux 环境下如果日志出现 permission denied，可以检查目录归属和权限，例如使用 ls -ld /opt/zotero-ai/data 查看。不要简单粗暴地给全局最高权限，更稳妥的做法是查看容器运行用户 ID，再将目录授权给对应用户。

Windows 与 macOS 用户则要确认挂载路径位于 Docker 允许共享的位置，否则容器可能启动成功但写入失败。

连接 Zotero 与模型服务

Zotero 连接方式

Zotero AI 工具通常有三种连接方式：

• 通过 Zotero 导出的条目、PDF 文件夹或 Better BibTeX 等插件生成的数据进行处理
• 通过 Zotero 本地数据路径读取元信息
• 通过工具自身插件或接口把内容发送到服务端

无论哪种方式，都建议先使用少量测试文献验证流程，确认题名、作者、摘要和 PDF 解析正常，再批量导入。

模型配置要点

常见变量包括接口地址、密钥、模型名称、嵌入模型名称、超时时间和并发数量。若使用本地模型服务，接口地址不要写成容器内无法访问的本机回环地址。

对容器来说，127.0.0.1 指向容器自身，不一定是宿主机。 Docker Desktop 可尝试使用 host.docker.internal，Linux 则可按项目建议配置宿主机网关地址。

启动验证与日常维护

启动验证：容器启动后，先执行 docker ps 确认状态为 Up，再打开浏览器访问 http://宿主机地址:8080。如果页面打不开，先看端口是否写错，再看防护规则是否放行该端口，最后查看容器日志。

若页面正常但 AI 请求失败，重点检查模型接口地址、密钥、模型名称和网络连通性。

日常维护：建议每周或每次大量导入文献前备份数据目录，尤其是索引库和配置文件。升级前先记录当前镜像版本，拉取新版本后重建容器。如果新版本出现解析异常、页面报错或模型调用失败，可将镜像标签改回旧版本并重新启动——这就是固定版本号的价值。不要在没有备份的情况下直接删除整个工作目录。

常见问题排查

• 端口被占用：表现为容器无法启动或日志提示 bind failed。解决方式是更换宿主机左侧端口，例如从 8080:3000 改为 18080:3000。
• 数据没有保存：通常是目录没有挂载，或挂载到了错误路径。应核对项目文档中的容器内部路径。
• PDF 解析乱码或失败：可检查文件是否损坏、是否为扫描件、是否需要 OCR 支持，以及项目是否安装了对应解析组件。
• AI 回复很慢：可能是模型接口延迟、文档切片过大、并发设置过高或设备资源不足。可降低并发、缩短单次输入长度，或先建立索引再提问。
• 容器不断重启：使用 docker logs zotero-ai 查看报错，常见原因包括必要环境变量缺失、配置文件格式错误、目录无写入权限或数据库初始化失败。

安全边界与实用建议

文献工具经常处理未发表稿件、实验数据、批注和个人阅读记录。部署时不要把服务直接暴露到公网，至少应设置访问认证、限制来源地址，并避免在日志中输出密钥。

密钥管理：密钥应通过环境变量或受控配置文件传入，不要写进公开仓库。团队共用时要明确哪些文献可以上传到模型接口，哪些只能在本地处理。

稳妥流程：

1. 先固定镜像版本，创建独立数据目录
2. 用少量文献测试解析、索引和问答
3. 确认无误后批量导入
4. 上线前设置访问保护
5. 升级前备份数据并保留旧版本回退方案

只要把镜像、端口和数据目录三件事配置清楚，Docker 部署 Zotero AI 并不复杂，后续维护也会轻松很多。