Open Notebook 数据库配置指南基于 SurrealDB 的环境变量、部署拓扑与多实例隔离【免费下载链接】open-notebookAn Open Source implementation of Notebook LM with more flexibility and features项目地址: https://gitcode.com/GitHub_Trending/op/open-notebookOpen Notebook 使用 SurrealDB 作为其唯一的主数据存储承载笔记、来源、笔记本、凭证等全部业务数据。本文基于 docs/5-CONFIGURATION/database.md 展开完整覆盖五个SURREAL_*核心变量的语义与默认值、三种主流部署拓扑下的连接串写法、端口暴露的安全边界以及如何用同一实例多 Namespace/Database支持多个独立部署并延伸到仓库源码层的连接建立与自动迁移机制。SurrealDB 在 Open Notebook 中的角色从源码结构看SurrealDB 是 Open Notebook 的持久化基座而非可选组件全部数据访问都收敛在 open_notebook/database/repository.py 这一层对外提供repo_query、repo_create、repo_upsert、repo_relate等通用封装业务模块通过它们读写 SurrealDB数据库结构表、关系、索引完全由版本化迁移脚本维护位于 open_notebook/database/migrations 目录下以1.surrealql23.surrealql编号排列每个迁移都配有一个N_down.surrealql回滚脚本迁移执行器位于 open_notebook/database/async_migrate.py版本号记录在_sbl_migrations表中不存在时视为版本 0即全新库。因此数据库连接配置是否正确直接决定了 API、Worker 能否启动并完成自动迁移这是本文将环境变量放在第一优先级讲解的原因。五个核心环境变量字段语义与默认值Open Notebook 通过环境变量定位并认证 SurrealDB官方文档 docs/5-CONFIGURATION/environment-reference.md 将它们标为必需项变量必需?默认值说明SURREAL_URL是ws://surrealdb:8000/rpcSurrealDB WebSocket 连接地址路径固定为/rpcRPC 端点SURREAL_USER是rootSurrealDB 登录用户名SURREAL_PASSWORD是rootSurrealDB 登录密码SURREAL_NAMESPACE是open_notebook逻辑命名空间NamespaceSURREAL_DATABASE是open_notebookNamespace 下的具体数据库Database名实际代码与文档互为印证在 open_notebook/database/repository.py 中连接 URL、密码、Namespace、数据库名均从环境变量读取其中密码读取SURREAL_PASSWORD、缺失时回退SURREAL_PASS再回退字面量root而 Namespace 与数据库名缺省时统一回退open_notebook。连接建立的真实调用链repository.py 中的db_connection()是每次访问数据库都会执行的上下文管理器async with db_connection() as connection: # connection 已登录并 use 到目标 Namespace/Database其内部顺序为用SURREAL_URL构造AsyncSurreal客户端调用signin()传入用户名SURREAL_USER与密码见上文回退逻辑调用use(get_database_namespace(), get_database_name())切到目标逻辑空间业务查询结束后自动close()。这解释了为什么五者必须同时正确仅 URL 正确而SURREAL_USER/SURREAL_PASSWORD与 SurrealDB 启动参数不一致会认证失败Namespace/Database 与迁移目标不一致则数据会落错库。向后兼容的遗留变量代码保留了早期命名方式的回退逻辑未设置SURREAL_URL时会按SURREAL_ADDRESS默认localhost与SURREAL_PORT默认8000拼出ws://{address}/rpc:{port}见 repository.py。新部署请直接使用规范的SURREAL_URL全量 URL。三种部署拓扑与推荐配置官方文档 docs/5-CONFIGURATION/database.md 给出了三个典型场景区别只在于SURREAL_URL的主机名怎么写——这正是最容易配错的地方。场景一SurrealDB 与 Open Notebook 同属一个 docker compose推荐这也是 docs/1-INSTALLATION/docker-compose.md 描述的推荐安装方式。容器之间通过 compose 内部网络通信主机名直接使用服务名surrealdbSURREAL_URLws://surrealdb:8000/rpc SURREAL_USERroot SURREAL_PASSWORDroot SURREAL_NAMESPACEopen_notebook SURREAL_DATABASEopen_notebook仓库根目录的 docker-compose.yml 即为这一拓扑的标准落地surrealdb服务以rocksdb:/mydata/mydatabase.db启动、数据卷映射./surreal_data:/mydataopen_notebook服务通过depends_on等待其就绪两个服务共用同一份SURREAL_USER/SURREAL_PASSWORD通过${SURREAL_USER:-root}插值可在.env中一并覆盖保证两侧始终同步。场景二SurrealDB 跑在宿主机、Open Notebook 跑在 Docker此时容器内无法使用surrealdb服务名需要指向宿主机 IP 或 Docker 提供的特殊域名host.docker.internalSURREAL_URLws://your-machine-ip:8000/rpc # 或 host.docker.internal SURREAL_USERroot SURREAL_PASSWORDroot SURREAL_NAMESPACEopen_notebook SURREAL_DATABASEopen_notebook重要安全提示原文档强调如果 SurrealDB 容器按文档默认只把端口发布到127.0.0.1那么宿主机 IP 上其实是连不通的。若确实需要从宿主机侧访问请有意识地重新发布端口——参考仓库根目录的 docker-compose.override.yml.example并且务必放到防火墙或 SSH 隧道之后同时把SURREAL_USER/SURREAL_PASSWORD换成真实强凭证。场景三SurrealDB 与 Open Notebook 跑在同一台机器适用于两者都直接跑在宿主机本地的场景或者已弃用的单容器方案见 docs/1-INSTALLATION/single-container.mdv2 将移除仓库中仍有示例 examples/docker-compose-single.yml其内部以ws://localhost:8000/rpc覆盖连接SURREAL_URLws://localhost:8000/rpc SURREAL_USERroot SURREAL_PASSWORDroot SURREAL_NAMESPACEopen_notebook SURREAL_DATABASEopen_notebook三种场景仅替换第一行主机名其余四行保持一致这正是 Open Notebook 支持换库不换逻辑的设计体现。端口暴露边界默认只绑 127.0.0.1 的用意仓库根目录 docker-compose.yml 对 SurrealDB 端口做了刻意约束ports: # Bound to localhost only: the open_notebook service reaches this over # the internal compose network regardless, so the host port is purely # for local debugging (e.g. Surrealist, surreal sql). - 127.0.0.1:8000:8000注释写得很清楚Open Notebook 容器走 compose 内部网络根本不需要宿主机把 8000 端口暴露给外部宿主机的端口仅用于本地调试如用 Surrealist 可视化工具或surreal sql命令行。若改成0.0.0.0任何能触达宿主机的人都可以用默认的root:root以管理员身份连接数据库。若确实需要跨机器访问例如在笔记本上用 Surrealist 连开发机官方提供了 docker-compose.override.yml.exampleservices: surrealdb: ports: !override - 8000:8000注意其中的关键细节必须使用!override语法替换而非合并 portsDocker Compose 需 v2.24.4否则新旧两条端口规则共存会报 port is already allocated。更稳妥的做法是先通过 SSH 隧道或防火墙限定访问来源再以真实凭证启动 SurrealDB把SURREAL_USER/SURREAL_PASSWORD写入.env两个服务会自动同步读取见 docker-compose.yml 的注释说明密码含空格时以 exec 列表形式传参避免被 shell 拆分。启动期的自动迁移为什么连上库还不够正确配置好五个环境变量后启动流程还有一个与数据库直接相关的环节自动执行迁移。在 api/main.py 中_run_database_migrations()会在 FastAPI 的lifespan里被调用先执行_wait_for_database()做只读的就绪探测——ping()会真实发起一次连接并查询_sbl_migrations版本但对连接失败采用指数退避重试不重试迁移本身避免掩盖真正的 schema 错误从而容忍 compose 环境下 API 比数据库先起的时序问题对比当前版本与内置迁移列表长度needs_migration()有未应用迁移时逐条执行N.surrealql成功后在_sbl_migrations表写入新版本号失败则快速失败fail fast拒绝用过期 schema 启动 API。迁移脚本的加载逻辑见 open_notebook/database/async_migrate.pyup_migrations列表按序注册了open_notebook/database/migrations/1.surrealql到23.surrealqldown_migrations对应每个N_down.surrealql支持单步回滚。对应测试可参考 tests/test_startup_migration_retry.py。实践意义如果你新建了一套带自定义 Namespace/Database 的库却忘了在其中执行迁移API 会启动失败或报 schema 缺失——因为迁移只对代码默认与连接目标指向的那套逻辑空间自动执行。这也是为什么文档建议保持默认的open_notebook值或确保每个新库都经过一次正常启动。写入重试与网络代理两个隐藏配置除了五个核心变量数据库行为还受两组环境变量影响均记录在 docs/5-CONFIGURATION/environment-reference.md命令级重试数据库写入的容错变量默认值说明SURREAL_COMMANDS_RETRY_ENABLEDtrue是否启用失败重试SURREAL_COMMANDS_RETRY_MAX_ATTEMPTS3最大重试次数SURREAL_COMMANDS_RETRY_WAIT_STRATEGYexponential_jitter退避策略exponential_jitter/exponential/fixed/randomSURREAL_COMMANDS_RETRY_WAIT_MIN1单次最小等待秒SURREAL_COMMANDS_RETRY_WAIT_MAX30单次最大等待秒在多人写入或事务冲突repository 对可重试冲突仅以 debug 级别记录日志见 repository.py的场景下合理调低MAX_ATTEMPTS、收紧等待区间可以让失败更早暴露。NO_PROXYWebSocket 代理陷阱Open Notebook 的 SurrealDB SDK 通过 WebSocket 通信而较新版本的websockets库会把ws://连接也塞进已配置的 HTTP 代理导致内部数据库主机被代理以 HTTP 403 拒绝API 与 Worker 双双无法启动。因此NO_PROXY必须显式包含内部主机host.docker.internalDocker 宿主机场景与surrealdbcompose 服务名。Open Notebook 在 open_notebook/utils/proxy.py 的ensure_internal_no_proxy()中会自动把host.docker.internal,surrealdb,localhost,127.0.0.1合并进no_proxy/NO_PROXY作为安全网但官方文档仍建议用户自行显式设置例如NO_PROXYlocalhost,127.0.0.1,host.docker.internal,surrealdb,.local注意该模块在 repository.py 导入时就执行API 与 Worker 两条进程路径都会触发可见这是数据库连通性的前置保障。多实例共库一个 SurrealDB 跑多套 Open NotebookSurrealDB 的逻辑隔离分两层Namespace命名空间之下可以有多个Database数据库。Open Notebook 官方文档明确说明想为不同用户部署多套 Open Notebook无需部署多个 SurrealDB 实例只需复用同一实例并用不同的 Namespace/Database 对即可。结合本文前面的机制落地方式如下每套 Open Notebook 部署使用各自唯一的SURREAL_NAMESPACE与SURREAL_DATABASE例如SURREAL_NAMESPACEtenant_aSURREAL_DATABASEopen_notebook另一套用tenant_b每套部署首次正常启动时会自动把迁移执行到自己的 Namespace/Database 中数据彼此物理隔离所有套共享同一个 SurrealDB 连接端点与认证账号也可在 SurrealDB 侧按用户权限做更细的账号拆分但 Open Notebook 侧只需关注这五个变量。需要提醒的是凭证数据在库内经OPEN_NOTEBOOK_ENCRYPTION_KEY加密存储见 docs/5-CONFIGURATION/environment-reference.md 与 docker-compose.yml多租户共库时每套部署务必使用不同的加密密钥避免一处泄漏殃及全部。常见问题排查速查结合 docs/1-INSTALLATION/docker-compose.md 与 docs/6-TROUBLESHOOTING/connection-issues.md 的思路把排查项收敛为三条启动即失败、日志含认证错误核对SURREAL_USER/SURREAL_PASSWORD是否与 surrealdb 容器启动参数--user/--pass一致。默认双root生产必须改迁移报错或表缺失确认SURREAL_NAMESPACE/SURREAL_DATABASE与首次初始化时一致且该 Namespace/Database 确实存在SurrealDB 通常会在首次use时自动创建但若你手动建库需保证迁移曾成功执行容器间连不通Docker 内请用服务名surrealdb同 compose或host.docker.internal宿主机不要写localhost同时确认端口未被防火墙拦截、NO_PROXY已放行内部主机。全部变量总表与按场景组合的.env示例Minimal / Production / Corporate 等可直接查阅 docs/5-CONFIGURATION/environment-reference.md它与本文共同构成 Open Notebook 数据库配置的完整参考。【免费下载链接】open-notebookAn Open Source implementation of Notebook LM with more flexibility and features项目地址: https://gitcode.com/GitHub_Trending/op/open-notebook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
