部署前需要了解什么

Logseq 是一款以大纲和双向链接为核心的知识管理工具。

配合 AI 笔记插件后，可以实现内容摘要、提问检索、写作辅助、标签整理等能力。

对于个人用户来说，本地部署可以减少环境差异。

对于小团队来说，Docker 部署便于统一版本、快速迁移和集中维护。

所谓“一键部署”，并不是完全不用理解配置。

而是把运行环境、依赖和启动流程封装到容器中。

用户重点处理镜像拉取、端口映射、数据目录挂载和环境变量即可。

在开始前，建议先确认三件事：

• 第一，部署的 Logseq AI 服务是否来自官方项目、可信社区或企业内部仓库。
• 第二，AI 能力调用的是本地模型还是外部模型接口。不同方案对机器性能、网络和费用要求差异很大。
• 第三，笔记数据是否包含敏感内容。若涉及工作资料、客户信息或未公开文档，应优先选择本地化或内网环境，并严格控制访问权限。

准备 Docker 运行环境

服务器或个人电脑需要先安装 Docker Engine。

桌面系统可使用 Docker Desktop，Linux 服务器可通过系统软件源安装。

安装完成后，在终端执行 docker version 查看客户端与服务端版本，执行 docker ps 确认服务正常。

建议预留至少 2GB 内存和 2 核 CPU；如果还要运行本地大模型，则需要根据模型规格增加内存、显存和磁盘空间。

目录方面，建议提前创建独立的数据路径，例如 /opt/logseq-ai/data、/opt/logseq-ai/config、/opt/logseq-ai/logs。

这样做的好处是：容器删除后数据仍然保留，后续升级、迁移、备份都更清晰。

不要把重要数据只放在容器内部，因为容器重建时内部临时文件可能被清空。

拉取 Logseq AI 镜像

镜像名称应以项目发布页或内部文档为准。

示例命令可写为：docker pull ghcr.io/logseq/logseq-ai:latest。

如果项目方提供了固定版本号，更建议使用明确版本，例如 ghcr.io/logseq/logseq-ai:1.2.0，而不是长期使用 latest。

固定版本便于排查问题，也方便在升级失败时回到旧版本。

拉取完成后，可执行 docker images 查看镜像是否存在。

若拉取速度慢或失败，应先检查镜像地址、账号权限、系统时间和 DNS 配置。

企业环境中如果使用私有镜像仓库，需要先执行登录命令，并确认当前账号拥有读取权限。

不要随意使用来源不明的第三方镜像，尤其不要把笔记数据挂载给无法确认构建来源的镜像。

使用 docker run 快速启动

最基础的启动命令可以参考：

docker run -d --name logseq-ai -p 3000:3000 -v /opt/logseq-ai/data:/app/data -v /opt/logseq-ai/config:/app/config -v /opt/logseq-ai/logs:/app/logs -e TZ=Asia/Shanghai --restart unless-stopped ghcr.io/logseq/logseq-ai:1.2.0

其中 -d 表示后台运行，--name 用于指定容器名称，-p 负责端口映射，-v 负责目录挂载，--restart unless-stopped 表示异常退出或主机重启后自动恢复。

端口映射的写法是“主机端口:容器端口”。

例如 -p 3000:3000 表示访问主机的 3000 端口，会转发到容器内部的 3000 端口。

如果主机 3000 已被占用，可以改为 -p 18080:3000，之后通过 http://服务器地址:18080 访问。

若只希望本机访问，可绑定到本地回环地址，例如 -p 127.0.0.1:18080:3000，这样外部设备无法直接连接，安全性更高。

数据目录如何配置更稳妥

数据目录通常包括笔记索引、向量数据、插件配置、运行日志和缓存文件。

挂载时要区分“必须持久化”和“可清理缓存”。

• 例如 /app/data 和 /app/config 通常应长期保留。
• 日志目录可以设置轮转策略，避免占满磁盘。
• 缓存目录如果项目文档说明可重建，则可按需清理。

不同镜像内部路径可能不同，部署前务必查看项目说明，不要机械套用示例路径。

Linux 环境中还要注意目录权限。

若容器使用非 root 用户运行，宿主机目录需要允许该用户读写。

可通过 docker logs logseq-ai 查看是否出现 permission denied。

权限调整不建议简单粗暴地开放所有写权限，更好的做法是根据容器用户 UID、GID 修改目录归属，或在 compose 文件中明确运行用户。

使用 Docker Compose 管理更方便

如果需要长期运行，推荐使用 Docker Compose。

可在 /opt/logseq-ai/docker-compose.yml 中定义服务名称、镜像版本、端口、挂载目录和环境变量。

之后使用 docker compose up -d 启动，使用 docker compose down 停止，使用 docker compose logs -f 查看日志。

相比单条命令，Compose 文件更适合团队交接，也便于记录配置变更。

环境变量部分可能包括 AI 服务地址、API Key、默认模型、最大上下文长度、上传文件大小限制等。

敏感参数不建议直接写在公开仓库中，可放入 .env 文件并限制访问权限。

若对接外部模型接口，应设置合理的超时、重试和调用额度，避免异常循环导致资源消耗过高。

插件连接与访问验证

容器启动后，先执行 docker ps 确认状态为 Up，再执行 docker logs --tail=100 logseq-ai 查看是否有启动成功提示。

浏览器访问对应地址，若能看到服务页面或健康检查结果，说明端口映射基本正常。

随后在 Logseq 客户端的 AI 笔记插件中填写服务地址，例如 http://127.0.0.1:18080 或内网地址，并进行一次简单摘要测试。

如果插件提示连接失败，优先检查四点：

• 服务地址是否填错
• 宿主机端口是否开放
• 容器日志是否报错
• 插件版本是否与服务端兼容

桌面端访问本机容器时通常用 127.0.0.1；局域网其他设备访问时要使用部署主机的内网 IP，并确认系统防火墙规则允许该端口通过。

升级、备份与回滚策略

升级前先备份数据目录和配置文件，例如打包 /opt/logseq-ai 下的关键目录。

升级步骤建议为：

1. 记录当前镜像版本
2. 停止容器
3. 拉取新镜像
4. 使用相同挂载目录启动新容器
5. 完成验证后再清理旧镜像

不要在没有备份的情况下直接覆盖运行，尤其是涉及数据库结构或索引格式变化的版本。

回滚时，停止新容器，重新使用旧镜像版本启动，并挂载升级前备份的数据目录。

如果新版本已经改写了数据结构，直接使用同一目录回滚可能失败，因此重要升级前最好做完整快照。

对于团队场景，建议先在测试环境验证插件功能、搜索结果和 AI 输出稳定性，再安排正式环境升级。

常见问题排查

端口被占用：执行 docker ps 或系统端口查看命令，确认 3000 是否已被其他服务使用，改用 18080 等空闲端口即可。

容器反复重启：查看日志，多数与环境变量缺失、配置文件格式错误或目录权限不足有关。

访问页面空白：检查浏览器控制台、反向转发配置和服务基础路径设置。

AI 返回慢：可能是模型响应慢、机器资源不足或索引规模过大，可降低并发、缩小上下文长度或优化索引。

数据没有保存：多半是目录没有正确挂载，或挂载到了错误路径。可进入容器查看实际写入位置，也可在宿主机目录中创建测试文件验证映射关系。

插件功能异常：确认 Logseq 客户端、AI 插件和服务端版本组合是否匹配，必要时回到稳定版本。

日志增长过快：配置日志轮转或定期清理，避免影响整机运行。

安全边界与实用建议

Logseq AI 涉及笔记内容解析与模型调用，安全边界要提前设定。

• 个人部署时，尽量只绑定本机地址或内网地址。
• 团队部署时，应增加访问认证、最小权限账号和日志审计。
• 不要把服务端口直接暴露到不可信环境。
• 不要把长期有效的接口密钥写入前端页面或共享文档。

实用建议是：

• 生产环境使用固定镜像版本。
• 配置文件纳入变更记录。
• 数据目录定期备份。
• 升级前先测试。
• 出现异常先看日志再改配置。

对于重要知识库，可将原始 Logseq 图谱、AI 索引和服务配置分别备份，避免单点故障。

只要把镜像来源、端口映射、目录持久化和权限控制这几项做好，Docker 部署 Logseq AI 就能兼顾便利性与稳定性。