Open Notebook 安装指南：从安装路线选择到 Docker Compose、源码运行与 Windows 原生部署的完整实践

本文基于 open-notebook 仓库中的官方安装文档（安装指南）展开，系统讲解四条安装路线的适用场景与取舍依据、系统资源要求、AI 供应商（云/本地）选型、安装前检查清单，并结合仓库根目录的 docker-compose.yml、Makefile、.env.example 等真实配置与源码，说明每个配置项（如加密密钥、数据库连接、数据卷）背后的实际作用，帮助你在 5～15 分钟内完成部署，并具备排查安装期常见问题的能力。

一、安装路线总览：四条路径如何选

open-notebook 提供四条安装路线，选择依据是"你的环境 + 使用目的"：

路线	文档	适用人群	关键前提	耗时
Docker Compose（推荐）	Docker Compose 指南	大多数用户，生产可用	Docker Desktop	约 5 分钟
单容器（已弃用）	Single Container 指南	PikaPods / Railway / 共享托管等极简场景	Docker	约 2 分钟
从源码运行	From Source 指南	开发者/贡献者	Python 3.11+、Node.js 18+、Docker	约 10 分钟
Windows 原生（无 Docker）	Windows Native 指南	Windows ARM64、无 Hyper-V/Docker 的系统	Python 3.12+、Node.js、SurrealDB、uv	约 15 分钟

各路线的核心特征：

• Docker Compose：多容器架构、服务隔离清晰、易扩展，Mac/Windows/Linux 全平台支持，官方推荐路线；
• 单容器：v1-latest-single 镜像已标记 Deprecated，将在 v2 移除，v2 发布前仍会收到更新，但不再为其新增功能与文档；
• 源码运行：完全掌控代码、便于调试与修改，代价是需自行拉起数据库、API、Worker、前端四个进程；
• Windows 原生：面向无法使用 Docker/WSL 的 Windows ARM64 用户。

隐私优先用户：任何安装路线都可以搭配 Ollama 实现 100% 本地 AI，见 本地快速上手。

二、系统要求与 AI 供应商选型

2.1 硬件要求

级别	RAM	存储	CPU	其他
最低	4GB	2GB（应用）+ 文档空间	任意现代处理器	联网（离线可用 Ollama）
推荐	8GB+	10GB+（文档与模型）	多核处理器	GPU（可选，加速本地模型）

2.2 AI 供应商选项

云端（按量付费）：OpenAI（GPT-4 系列）、Anthropic（Claude 3.5 Sonnet）、Google Gemini、Groq（超快推理），以及 Mistral、DeepSeek、xAI、OpenRouter 等。成本通常在每 1K token $0.01–$0.10，速度亚秒级，但数据会发送到云端。

本地（免费、私有）：Ollama（本地运行开源模型）、LM Studio、Hugging Face 模型。零 API 成本，速度取决于硬件，100% 离线。

从仓库的 examples/ 目录可以看到官方为此提供了现成的组合编排：docker-compose-ollama.yml、docker-compose-single.yml、docker-compose-dev.yml 与完整的本地全家桶 docker-compose-full-local.yml，每个示例都带详细注释。

三、安装前检查清单

• [ ] Docker（Docker 路线）或 Node.js 18+（源码路线）；
• [ ] 至少一个 AI 供应商 API Key（OpenAI/Anthropic 等），或愿意使用免费的本地模型；
• [ ] 至少 4GB 可用内存；
• [ ] 稳定网络（或基于 Ollama 的离线方案）。

四、Docker Compose 路线详解（推荐路线）

4.1 官方 docker-compose.yml 完整配置

仓库根目录的 docker-compose.yml 即官方部署文件，由 surrealdb 与 open_notebook 两个服务组成。完整内容与注释如下（节选自 安装文档 的 Option C，与仓库文件一致）：

services:
  surrealdb:
    image: surrealdb/surrealdb:v2
    # Credentials default to root:root for a zero-config local setup. Before
    # exposing this instance to a network, set SURREAL_USER / SURREAL_PASSWORD
    # in a .env file (see .env.example) — they are applied here and to the
    # open_notebook service below, so the two always stay in sync.
    command: ["start", "--log", "info", "--user", "${SURREAL_USER:-root}", "--pass", "${SURREAL_PASSWORD:-root}", "rocksdb:/mydata/mydatabase.db"]
    user: root  # Required for bind mounts on Linux
    ports:
      - "127.0.0.1:8000:8000"   # 仅绑定 localhost，供本机调试使用
    volumes:
      - ./surreal_data:/mydata
    environment:
      - SURREAL_EXPERIMENTAL_GRAPHQL=true
    restart: always
    pull_policy: always

  open_notebook:
    image: lfnovo/open_notebook:v1-latest
    ports:
      - "8502:8502"  # Web UI
      - "5055:5055"  # REST API
    environment:
      # REQUIRED: Change this to your own secret string
      # This encrypts your API keys in the database
      - OPEN_NOTEBOOK_ENCRYPTION_KEY=change-me-to-a-secret-string
      - SURREAL_URL=ws://surrealdb:8000/rpc
      - SURREAL_USER=${SURREAL_USER:-root}
      - SURREAL_PASSWORD=${SURREAL_PASSWORD:-root}
      - SURREAL_NAMESPACE=open_notebook
      - SURREAL_DATABASE=open_notebook
    volumes:
      - ./notebook_data:/app/data
    depends_on:
      - surrealdb
    restart: always
    pull_policy: always

获取该文件有三种方式：直接 curl 下载官方文件、从仓库根目录复制（即 docker-compose.yml），或按上述内容手工创建。镜像同时发布在 Docker Hub（lfnovo/open_notebook）与 GitHub Container Registry（ghcr.io/lfnovo/open-notebook），后者适合作为备选拉取源。

4.2 配置项的源码级解读

几个关键配置项的实际作用，可以从仓库源码中得到印证：

OPEN_NOTEBOOK_ENCRYPTION_KEY（必填）：用于加密存储数据库中的 API 凭据。从 encryption.py 可以看到，该值接受任意字符串（内部会派生 Fernet 密钥），优先级为 OPEN_NOTEBOOK_ENCRYPTION_KEY_FILE（Docker secrets）> OPEN_NOTEBOOK_ENCRYPTION_KEY（环境变量）；若两者都未设置，生产部署时会直接报错提示，不允许裸跑。

SURREAL_URL / SURREAL_USER / SURREAL_PASSWORD：应用通过 WebSocket RPC 连接 SurrealDB（ws://surrealdb:8000/rpc，走 compose 内部网络）。${SURREAL_USER:-root} 的默认值写法保证数据库服务与应用服务始终使用同一套凭据；.env.example 中同样说明：暴露到网络前必须修改默认的 root:root。

127.0.0.1:8000:8000 端口绑定：SurrealDB 宿主机端口刻意只绑到回环地址——compose 内部网络本就能互通，宿主机端口纯属本地调试用途（Surrealist 图形界面、surreal sql）。若暴露到 0.0.0.0，任何能访问主机的用户都能用默认 root:root 连库。

user: root（surrealdb 服务）：Linux 上 Docker 创建 bind mount 目录的属主是 root，而 SurrealDB 默认以非 root 用户运行，会导致 Permission denied / Failed to create RocksDB directory。这也是官方 compose 文件直接写入 user: root 的原因。

数据卷：./surreal_data:/mydata 存数据库文件，./notebook_data:/app/data 存应用数据。从 config.py 可推断应用数据目录内至少包含 uploads/（上传文档）、sqlite-db/（LangGraph 检查点）、podcasts/（播客输出）与 tiktoken-cache/ 等子目录。

可选的重型运行时开关：docker-compose.yml 中还注释了两个可选环境变量——OPEN_NOTEBOOK_ENABLE_DOCLING=true（Docling 引擎 + OCR + 图片源，含大型 ML 依赖栈）与 OPEN_NOTEBOOK_ENABLE_CRAWL4AI=true（本地 Crawl4AI，捆绑 Chromium）；也可用 CRAWL4AI_API_URL 指向远程 Crawl4AI 服务器。此外 OPEN_NOTEBOOK_WORKER_MAX_TASKS 控制 worker 并发后台任务数（默认 5），单 GPU/本地 LLM 场景建议设为 1 避免并行请求压垮模型。

4.3 启动与验证

# 启动（首次约 15-20 秒）
docker compose up -d

# 检查状态
docker compose ps

# API 健康检查，应返回 {"status": "healthy"}
curl http://localhost:5055/health

浏览器访问 http://localhost:8502 即可看到界面。

4.4 配置 AI Provider 与创建首个 Notebook

1. 进入 Settings → API Keys，点击 Add Credential；
2. 选择供应商（OpenAI/Anthropic/Google 等），命名并粘贴 API Key；
3. Save 后点击 Test Connection，应显示成功；
4. 点击 Discover Models → Register Models 完成模型注册；
5. 点击 New Notebook，命名（如 "My Research"）并 Create。

至此获得一个完整可用的实例。

4.5 追加 Ollama（本地免费模型）

最省事的方式是直接使用官方示例文件 examples/docker-compose-ollama.yml；手工方式则是在现有 docker-compose.yml 中加入：

  ollama:
    image: ollama/ollama:latest
    ports:
      - "11434:11434"
    volumes:
      - ollama_models:/root/.ollama
    restart: always

volumes:
  ollama_models:

然后：

docker compose restart
docker exec open-notebook-local-ollama-1 ollama pull mistral

在 Settings UI 中添加 Ollama 凭据，Base URL 填 http://ollama:11434（容器间网络地址），再 Test Connection 与 Discover Models。

4.6 环境变量参考

变量	作用	示例
OPEN_NOTEBOOK_ENCRYPTION_KEY	凭据加密密钥（必填，建议 ≥16 字符）	my-secret-key
SURREAL_URL	数据库连接	ws://surrealdb:8000/rpc
SURREAL_USER / SURREAL_PASSWORD	数据库用户/密码	root
SURREAL_NAMESPACE / SURREAL_DATABASE	命名空间/库名	open_notebook
API_URL	API 对外 URL	http://localhost:5055
OPEN_NOTEBOOK_EMBEDDING_BATCH_SIZE	覆盖 embedding 批大小，CPU-only 本地部署建议 8	50

完整列表见 环境变量参考。

4.7 日常运维命令

docker compose down          # 停止
docker compose logs -f       # 查看全部日志（-f api 看单服务）
docker compose restart       # 重启
docker compose down && docker compose pull && docker compose up -d   # 升级到最新版
docker compose down -v       # 删除全部数据（危险）

4.8 安装期故障排查

• "Cannot connect to API"：依次 docker ps → docker compose ps → docker compose logs api；首次启动可能需 20-30 秒；
• 端口冲突：8502 被占用时改为 "8503:8502"，然后访问 http://localhost:8503；
• 凭据问题：在 Settings → API Keys 中 Test Connection，失败则到供应商网站核实 Key 与账户额度，必要时删除重建凭据；
• 数据库连接问题：docker compose logs surrealdb 查看日志；需要重置时 docker compose down -v && docker compose up -d；
• Linux 数据库权限问题：日志出现 Permission denied 时，为 surrealdb 服务补上 user: root 后重建。

更多问题见 快速修复。

五、从源码安装（开发者路线）

适合需要读代码、调试、提 PR 的场景。前置条件：Python 3.11+（pyproject.toml 中 requires-python = ">=3.11,<3.13"，当前版本 1.14.0）、Node.js 18+、Git、Docker（跑 SurrealDB）、uv（curl -LsSf https://astral.sh/uv/install.sh | sh）。

5.1 九步快速搭建

# 1. 克隆仓库
git clone https://gitcode.com/GitHub_Trending/op/open-notebook.git
cd open-notebook

# 2. 安装 Python 依赖
uv sync
uv pip install python-magic

Conda 用户可改为：conda create -n open-notebook python=3.11 -y && conda activate open-notebook && conda install -c conda-forge uv nodejs -y && uv sync。在 conda 环境内安装 uv 可保证 make start-all、make api 等 Makefile 命令照常工作。

# 3. 启动 SurrealDB（终端 1）
make database        # 等价于 docker compose up surrealdb

# 4. 准备环境变量
cp .env.example .env
# 编辑 .env，至少设置 OPEN_NOTEBOOK_ENCRYPTION_KEY=my-secret-key

# 5. 启动 API（终端 2）
make api
# 等价于 uv run --env-file .env uvicorn api.main:app --host 0.0.0.0 --port 5055

# 6. 启动 Worker（终端 3）
make worker
# 等价于 uv run --env-file .env surreal-commands-worker --import-modules commands

# 7. 启动前端（终端 4）
cd frontend && npm install && npm run dev

访问地址：前端 http://localhost:3000、API 文档 http://localhost:5055/docs、数据库 http://localhost:8000。之后在浏览器 Manage → Models 中配置供应商凭据并 Discover Models。

Worker 是必需组件：内容抽取、embedding、insight 等处理都以后台任务形式派发给独立的 worker 进程消费。不启动 worker 的话，所有 source 会永远停在 Source processing status: CommandStatus.NEW。对照 Makefile 可以看到，worker-start 实际执行 uv run --env-file .env surreal-commands-worker --import-modules commands --max-tasks ${OPEN_NOTEBOOK_WORKER_MAX_TASKS:-5}，即默认并发 5 个任务，与 docker-compose 中的说明一致。make start-all 会一次性拉起 Database + API + Worker + Frontend，上述分步方式便于逐个查看日志。

5.2 开发工作流

make ruff                      # 格式化与 lint（ruff check . --fix）
make lint                      # 类型检查（uv run python -m mypy .）
uv run pytest tests/           # 运行测试套件
make start-all                 # 一键启动全部服务
make clean-cache               # 清理 __pycache__ 等缓存

排查提示：Python 版本过旧时可用 uv sync --python 3.11 指定版本；端口 5055 被占用可换 --port 5056；数据库连不上时 docker ps 与 docker logs surrealdb 定位。深入开发可继续阅读 开发环境指南、架构总览 与 贡献指南。

六、单容器路线（已弃用）与云端平台

单容器镜像 lfnovo/open_notebook:v1-latest-single（GHCR 同名）适合 PikaPods、Railway、Render、DigitalOcean App Platform、Heroku、Coolify、EasyPanel 等托管平台。本地最小配置：

services:
  open_notebook:
    image: lfnovo/open_notebook:v1-latest-single
    ports:
      - "8502:8502"  # Web UI
      - "5055:5055" # API
    environment:
      - OPEN_NOTEBOOK_ENCRYPTION_KEY=change-me-to-a-secret-string
      - SURREAL_URL=ws://localhost:8000/rpc
      - SURREAL_USER=root
      - SURREAL_PASSWORD=root
      - SURREAL_NAMESPACE=open_notebook
      - SURREAL_DATABASE=open_notebook
    volumes:
      - ./data:/app/data
    restart: always

部署到任何云平台时，最低要求是设置 OPEN_NOTEBOOK_ENCRYPTION_KEY 环境变量并为 /app/data（及 /mydata）配置持久化存储。与 Compose 路线的取舍对比：

维度	单容器	Docker Compose
部署时间	2 分钟	5 分钟
复杂度	极简	中等
服务形态	全部打包在一个容器	服务分离
可扩展性	有限	优秀
内存占用	~800MB	~1.2GB

仓库还提供了一个面向 EasyPanel 的官方模板 examples/easypanel/（含 meta.yaml 与 index.ts），它会自动创建 Open Notebook 应用 + 独立 SurrealDB 两个服务，并代为生成数据库密码、加密密钥与（可选的）应用密码，详见 examples/easypanel/README.md。

七、Windows 原生安装（无 Docker / WSL）

面向 Windows ARM64、无 Hyper-V 或偏好原生安装的用户。前置软件：

软件	安装方式	必需
Git	winget install Git.Git	是
Python 3.12+	由 uv 自动安装	是
Node.js 18+	winget install OpenJS.NodeJS	是
uv	pip install uv	是
SurrealDB	scoop install surrealdb	是

快速上手：克隆仓库后 uv sync，再 cd frontend && npm install；复制 .env.example 为 .env 并填入 API Key；然后四个终端各启动一个服务：

REM 终端 1 — SurrealDB
surreal start --user root --pass root --bind 127.0.0.1:8000 rocksdb:%DATA_FOLDER%\surrealdb

REM 终端 2 — API
uv run --env-file .env run_api.py

REM 终端 3 — Worker（模块方式规避 Windows "canonicalize" 错误）
set PYTHONPATH=%CD%
uv run --env-file .env python -m surreal_commands.cli.worker --import-modules commands

REM 终端 4 — 前端
cd frontend && npm run dev

最终访问 http://127.0.0.1:3000。文档同时给出了自制的 start-open-notebook.bat 一键启动脚本模板（用 start 命令分别拉起四个窗口）。

四个必须知道的 Windows 特有问题：

1. Python 版本错乱（ModuleNotFoundError: No module named 'langgraph.checkpoint.sqlite'）：系统装了多个 Python，venv 的 activate 未正确覆盖。解决：一律用 uv run python run_api.py 而非直接调 .venv\Scripts\python.exe；
2. 数据库健康检查超时（WARNING: Database health check timed out after 2 seconds）：SurrealDB 绑定在 127.0.0.1 而 .env 里写的是 localhost，两者在 Windows 上不一定等价。必须写 SURREAL_URL="ws://127.0.0.1:8000/rpc"；
3. Worker 报 Failed to canonicalize script path：surreal-commands-worker.exe 找不到 commands 模块。解决：设置 PYTHONPATH=%ROOT% 后用模块方式启动 python -m surreal_commands.cli.worker --import-modules commands；
4. uv 解析 .env 失败（含反斜杠的 Windows 路径）：把 DATA_FOLDER 在 .env 中保持注释，改在 batch 脚本中 set DATA_FOLDER=C:\path\to\open-notebook-data。

目录组织上，官方建议代码与数据分离：源码放 open-notebook\，数据（surrealdb\、uploads\、sqlite-db\）放独立的 open-notebook-data\，避免升级/重装代码时误伤数据。端口规划：SurrealDB 8000、API 5055（/docs）、前端 3000。升级流程为 git pull && uv sync && cd frontend && npm install，.env 与数据目录不受影响。（该指南基于 Windows 11 ARM64 实测。）

八、安装完成后做什么

1. 配置模型：Settings 中选择 AI 供应商与默认模型；
2. 创建第一个 Notebook，开始组织研究材料；
3. 添加 Sources：PDF、网页链接、文档等；
4. 探索核心功能：Chat、Search、Transformations；
5. 继续阅读 完整用户指南。

九、生产部署延伸

面向生产环境的安装，官方将安全与部署话题独立成篇，安装完成后应继续阅读：

• 安全加固（含数据库凭据修改、加密密钥管理等）；
• 反向代理配置；
• 性能调优与高级配置。

十、小结

open-notebook 的安装体系围绕"一条推荐路线 + 三条备选路线"展开：绝大多数用户直接采用根目录 docker-compose.yml 拉起 SurrealDB 与 lfnovo/open_notebook:v1-latest 两个服务（5 分钟）；托管平台用户可用单容器镜像（注意其已弃用、v2 移除）；开发者通过 make database / api / worker / frontend 四个命令获得完整可控的运行环境；Windows 受限环境则走原生四终端方案。所有路线共享同一套核心配置——必填的 OPEN_NOTEBOOK_ENCRYPTION_KEY 加密密钥、SURREAL_* 数据库连接五件套与数据卷持久化——理解这些配置项在源码中的实际落点（加密派生逻辑、数据目录结构、worker 并发控制），就能从容应对安装期的绝大多数问题。