Open Notebook Windows 原生部署指南：无 Docker/WSL 环境下四服务架构、关键修复与运维实践

Open Notebook Windows 原生部署指南无 Docker/WSL 环境下四服务架构、关键修复与运维实践【免费下载链接】open-notebookAn Open Source implementation of Notebook LM with more flexibility and features项目地址: https://gitcode.com/GitHub_Trending/op/open-notebook本篇基于仓库文档 windows-native.md 展开面向无法或不希望使用 Docker/WSL 的 Windows 用户完整讲解 Open Notebook 在 Windows 上的原生安装流程、.env关键配置、四个典型 Windows 兼容性问题的根因与修复方案以及升级、端口规划与故障排查方法。读完本文你可以在一台纯净的 Windows含 ARM64机器上手动拉起 SurrealDB、API、Worker、Frontend 四服务并具备独立排查启动故障的能力。一、适用对象谁需要无 Docker方案文档明确了三条适用边界这决定了为什么不走 Docker Compose 安装路线Windows ARM64 用户Docker Desktop 与 WSL2 在 ARM64 上存在限制无 Hyper-V 的 Windows 版本部分精简版/旧版 Windows 不支持虚拟化管理程序Docker 无法运行偏好原生安装的用户架构更简单、调试更直接报错直接出现在自己的终端里而不是容器日志中。这套方案的核心思路是用uv管理 Python 虚拟环境与依赖用scoop/winget安装系统级组件Git、Node.js、SurrealDB再手动在四个终端分别启动服务——Open Notebook 官方并未随仓库发布一键启动脚本这也是后文所有手动命令的由来。二、前置依赖清单软件安装命令是否必需Gitwinget install Git.Git是Python 3.12由 uv 自动安装无需单独安装是Node.js 18winget install OpenJS.NodeJS是uvpip install uv是SurrealDBscoop install surrealdb是关于 Python 版本有一个值得注意的细节项目 pyproject.toml 声明requires-python 3.11,3.13因此uv sync会自动选择并安装 3.12 系列解释器到.venv——文档推荐Python 3.12与此一致。你甚至不需要在系统中预装 Pythonuv 会按需下载但也正因如此Windows 上若已存在多个系统 Python后续极易踩到解释器选错的坑见第四部分 Issue 1。三、快速开始从零到可访问的完整流程3.1 克隆代码并初始化环境cd %USERPROFILE%\Projects # 或你偏好的位置 git clone https://gitcode.com/GitHub_Trending/op/open-notebook cd open-notebook uv sync cd frontend npm install cd ..uv sync根据 uv.lock 锁文件在.venv中复现完整 Python 依赖FastAPI、LangGraph、SurrealDB 客户端等npm install为 Next.js 前端安装 Node 依赖前端源码位于 frontend 目录。3.2 配置.env含最关键的一处修改把 .env.example 复制为.env填入 API Key然后务必把SURREAL_URL的主机名从localhost改为127.0.0.1SURREAL_URLws://127.0.0.1:8000/rpc.env.example中默认的SURREAL_URLws://surrealdb:8000/rpc是 docker-compose 网络里的服务名原生安装时不存在该主机名必须手工改写。这个一个词之差就是文档 Issue 2 的根源后文详述。3.3 启动四个服务各占一个终端在open-notebook目录下开四个终端依次执行REM 可选让 Open Notebook 使用独立的数据目录对应下文 Issue 4 REM 在每个终端运行前设置或省略以使用默认 ./data set DATA_FOLDER%USERPROFILE%\Projects\open-notebook-data 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 报错见 Issue 3 set PYTHONPATH%CD% uv run --env-file .env python -m surreal_commands.cli.worker --import-modules commands REM 终端 4 — Frontend cd frontend npm run dev四个服务各自的角色SurrealDB端口 8000主数据库rocksdb 文件后端落在DATA_FOLDER\surrealdbAPI端口 5055FastAPI 服务。从入口脚本 run_api.py 可以看到API_HOST默认127.0.0.1、API_PORT默认5055、API_RELOAD默认true开发热重载最终加载的是 api/main.py 中的api.main:appWorkersurreal-commands后台任务执行器负责文档处理、播客生成等异步命令。仓库 Makefile 的worker-start目标在 POSIX 系统上用surreal-commands-worker --import-modules commands启动而 Windows 文档特意改用python -m surreal_commands.cli.worker模块调用形式来规避可执行文件路径解析问题Frontend端口 3000Next.js 开发服务器。启动顺序上建议先起 SurrealDB 再起 API。API 启动时会执行迁移等待逻辑api/main.py 定义了最多 12 次、间隔指数退避1s→5s 封顶的数据库可达性探测_wait_for_database探测通过后自动执行 SurrealQL 迁移迁移脚本 已按 23 个版本组织。因此即使你顺手先启动了 API它也会自己等待数据库就绪并自动升级 schema。最后访问http://127.0.0.1:3000即进入应用。四、推荐目录结构代码与数据严格分离文档强烈推荐把源码目录和数据目录分开YourProjectsFolder\ ├── open-notebook\ # 源码git clone │ ├── .venv\ # Python 虚拟环境uv 创建 │ ├── frontend\ # Next.js 前端 │ ├── commands\ # Worker 命令模块 │ └── .env # 你的配置 ├── open-notebook-data\ # 数据目录与代码分离 │ ├── surrealdb\ # 数据库文件 │ ├── uploads\ # 上传的文档 │ └── sqlite-db\ # LangGraph 检查点 └── start-open-notebook.bat # 你自建的一键启动脚本可选为什么要分离核心动机是更新或重装代码git pull/重新 clone时不会误伤数据。数据目录实际存放的正是 open_notebook/config.py 中定义的几个路径sqlite-db/checkpoints.sqliteLangGraph 会话检查点、uploads上传文件、podcasts生成的播客音频、tiktoken-cache分词缓存——这些目录在进程启动时会被自动创建。可选一键启动脚本仓库不附带启动器但你可以把下面内容保存为start-open-notebook.bat双击即用按需修改ROOT与DATA_ROOTecho off REM --- 修改这两个路径 --- set ROOT%USERPROFILE%\Projects\open-notebook set DATA_ROOT%USERPROFILE%\Projects\open-notebook-data set DATA_FOLDER%DATA_ROOT% set PYTHONPATH%ROOT% cd /d %ROOT% start SurrealDB surreal start --user root --pass root --bind 127.0.0.1:8000 rocksdb:%DATA_ROOT%\surrealdb start API cmd /k uv run --env-file .env run_api.py start Worker cmd /k uv run --env-file .env python -m surreal_commands.cli.worker --import-modules commands start Frontend cmd /k cd /d %ROOT%\frontend npm run devcmd /k让每个服务保留独立窗口方便定位是哪个服务报错。五、四个 Windows 关键问题症状、根因与修复这一节是原生安装方案的精华——四个问题全部来自 Windows 平台特性与项目默认配置之间的冲突。Issue 1用错了 Python 版本症状ModuleNotFoundError: No module named langgraph.checkpoint.sqlite且 traceback 指向系统 Python例如C:\Python314\而非.venv。根因Windows 上常存在多个 Python 版本venv 的activate.bat并不总能正确覆盖系统解释器于是明明装好了却调到了没有依赖的系统 Python。修复一律使用uv run而不是直接调用 pythonREM 错误 .venv\Scripts\python.exe run_api.py REM 正确 uv run python run_api.pyuv run保证在当前项目锁定的虚拟环境中执行绕开系统 PATH 污染。这也是文档全部启动命令都带uv run前缀的原因。Issue 2数据库健康检查超时localhost vs 127.0.0.1症状WARNING: Database health check timed out after 2 secondsSurrealDB 明明在运行前端却显示Database is offline。根因.env中写的是localhost而 SurrealDB 绑定的是127.0.0.1。在部分 Windows 环境下localhost会先解析到 IPv6 的::1与只监听 IPv4 的数据库握手失败。修复# 错误 SURREAL_URLws://localhost:8000/rpc # 正确 SURREAL_URLws://127.0.0.1:8000/rpc这与surreal start --bind 127.0.0.1:8000的绑定地址保持显式一致是最稳妥的组合。Issue 3Worker 报 Failed to canonicalize script path症状Failed to canonicalize script path根因surreal-commands-worker.exe这类可执行入口在 Windows 上无法定位项目内的 Pythoncommands模块包commands 目录下的任务注册模块。修复改为 Python 模块调用并显式设置PYTHONPATHset PYTHONPATH%ROOT% uv run --env-file .env python -m surreal_commands.cli.worker --import-modules commands--import-modules commands告诉 worker 加载commands包以注册任务处理器从源码结构看api/main.py 在 API 进程内也有命令注册动作而 Worker 进程是这些后台任务的真正执行者两者缺一不可。Issue 4DATA_FOLDER 含反斜杠导致 .env 解析失败症状warning: Failed to parse environment file .env at position X根因uv的.env解析器无法正确处理 Windows 反斜杠路径C:\Users\...中的转义问题。修复.env中把DATA_FOLDER保持注释状态改在批处理/终端中用set注入set DATA_FOLDERC:\path\to\open-notebook-data配套改动让 config.py 读取 DATA_FOLDER 环境变量当前仓库的 open_notebook/config.py 是硬编码DATA_FOLDER ./data数据默认落在源码目录内。文档建议做如下本地修改使其支持环境变量覆盖import os # ROOT DATA FOLDER - can be overridden via DATA_FOLDER environment variable DATA_FOLDER os.environ.get(DATA_FOLDER, ./data) # Rest of file uses DATA_FOLDER...改完后前文所有set DATA_FOLDER...才真正生效数据才会进入独立的open-notebook-data目录。若不修改此文件服务仍会默认使用%CD%\data——功能上可用只是失去了代码数据分离的保护。六、.env完整配置说明结合 .env.example 与文档Windows 原生部署下的关键配置项# 数据库 —— 必须使用 127.0.0.1 SURREAL_URLws://127.0.0.1:8000/rpc SURREAL_USERroot SURREAL_PASSWORDroot SURREAL_NAMESPACEopen_notebook SURREAL_DATABASEopen_notebook # 凭证加密密钥必填项建议 16 字符以上 OPEN_NOTEBOOK_ENCRYPTION_KEYchange-me-to-a-secret-string # AI 提供商 API Key也可通过 设置页 → API Keys 配置 OPENAI_API_KEYyour-key-here ANTHROPIC_API_KEYyour-key-here GOOGLE_API_KEYyour-key-here几点源码级的补充说明加密密钥api/main.py 在启动时检查OPEN_NOTEBOOK_ENCRYPTION_KEY未设置时会打印警告且API Key 加密将失败——这是 .env.example 中标注为 REQUIRED 的项原生部署时同样不能漏API 端口由 run_api.py 的API_HOST/API_PORT/API_RELOAD环境变量控制默认即 127.0.0.1:5055 且开启热重载无需额外配置Worker 并发度.env.example 提供OPEN_NOTEBOOK_WORKER_MAX_TASKS默认 5本地 LLM/单卡场景可设 1 串行处理注意该变量在 worker 启动时读取修改后必须重启 WorkerAI Key 的位置优先建议通过前端设置 → API Keys配置加密入库直接写.env是可选的兜底方式。七、AI 模型配置服务跑起来后在 Settings 页面添加模型。文档给出的常见模型名以实际账户可用为准提供商常用模型OpenAIgpt-4o、gpt-4o-mini、gpt-4-turbo、text-embedding-3-smallAnthropicclaude-sonnet-4-20250514、claude-3-5-sonnet-20241022、claude-3-5-haiku-20241022Googlegemini-3.5-flash、gemini-2.5-flash、gemini-2.5-proDeepSeekdeepseek-chat、deepseek-reasoner若使用本地 Ollama.env中可设置OLLAMA_API_BASE参见 .env.example实现 100% 离线运行。八、升级与维护新版本发布后升级流程非常简单——这正是代码/数据分离的收益cd open-notebook git pull uv sync cd frontend npm install cd ..然后重启全部四个服务。由于.env与open-notebook-data都在源码目录之外或受 git 保护升级过程不会丢失任何配置与数据API 重启时 api/main.py 的迁移逻辑还会自动把数据库 schema 升到最新若需要23 个迁移文件均含对应的_down回滚脚本。九、服务与端口总览服务端口URLSurrealDB8000ws://127.0.0.1:8000API5055http://127.0.0.1:5055/docsFrontend3000http://127.0.0.1:3000十、故障排查速查表服务起不来查端口占用netstat -ano | findstr :8000结束冲突进程taskkill /F /PID pid前端连不上 API先确认 API 存活访问 http://127.0.0.1:5055/docs检查.env中API_URL配置默认http://localhost:5055用于 webhook/回调等外部访问Worker 不处理任务查看 Worker 窗口报错绝大多数是PYTHONPATH未设置或用了错误的解释器回看 Issue 1/3确认启动命令为python -m surreal_commands.cli.worker --import-modules commands模块形式前端提示数据库离线先查SURREAL_URL是否误用localhostIssue 2再看 SurrealDB 终端窗口是否有启动错误。十一、适用前提与版本说明原文档注明在Windows 11 ARM64、Open Notebook v1.6.0上验证过当前仓库 pyproject.toml 版本为1.14.0核心启动链路run_api.py、open_notebook/config.py、surreal-commandsworker与文档描述一致但升级前仍建议核对 CHANGELOGCHANGELOG.md中的破坏性变更本方案要求完全手动管理四个终端进程适合 ARM64 受限环境或深度调试场景在标准 x64 Hyper-V 环境下Docker Compose 路线docker-compose.md依然是官方推荐的首选项若发现新的 Windows 特有问题欢迎按仓库贡献规范CONTRIBUTING.md反馈解决方案持续完善这份指南。【免费下载链接】open-notebookAn Open Source implementation of Notebook LM with more flexibility and features项目地址: https://gitcode.com/GitHub_Trending/op/open-notebook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考