从0到1部署open-notebook：Docker容器化方案全解析

你还在为AI笔记工具的复杂部署而烦恼吗？服务器配置、依赖安装、端口冲突...这些问题是否让你望而却步？本文将通过Docker容器化方案，带你从0到1轻松部署open-notebook，无需复杂环境配置，10分钟即可拥有属于自己的AI笔记系统。

读完本文你将获得：

• 两种部署方案的详细步骤（单容器/多容器）
• 环境变量配置最佳实践
• 数据持久化与备份策略
• 常见问题解决方案
• 生产环境优化建议

部署前准备

硬件要求

部署类型	内存	CPU	存储
单容器基础版	1GB+	1核+	10GB+
多容器生产版	2GB+	2核+	50GB+

软件依赖

• Docker Engine (20.10+)
• Docker Compose (v2+)

环境安装

# Ubuntu/Debian系统
sudo apt update
sudo apt install docker.io docker-compose
sudo systemctl start docker
sudo systemctl enable docker
sudo usermod -aG docker $USER

执行完成后需注销并重新登录，使Docker权限生效

两种部署方案对比与选择

方案对比

特性	单容器部署	多容器部署
容器数量	1个一体化容器	多个独立容器
复杂度	简单（适合新手）	中等（适合进阶用户）
资源占用	较低	较高但可控
扩展性	有限	灵活扩展
适用场景	个人使用、快速测试	团队协作、生产环境

方案选择建议

• 个人用户/新手：选择单容器部署，最简单的方式启动服务
• 开发者/企业用户：选择多容器部署，便于维护和扩展
• 云平台部署：单容器更适合PikaPods、Railway等PaaS平台

方案一：单容器快速部署

部署步骤

1. 创建项目目录

mkdir open-notebook && cd open-notebook

2. 创建docker-compose配置文件
   创建docker-compose.single.yml文件：

services:
  open_notebook_single:
    image: lfnovo/open_notebook:latest-single
    ports:
      - "8502:8502"  # Web界面端口
      - "5055:5055"  # API端口
    environment:
      - OPENAI_API_KEY=your_openai_key_here  # 替换为你的API密钥
      - OPEN_NOTEBOOK_PASSWORD=your_password  # 设置访问密码
    volumes:
      - ./notebook_data:/app/data          # 应用数据
      - ./surreal_single_data:/mydata      # 数据库文件
    restart: always

3. 启动服务

docker compose -f docker-compose.single.yml up -d

4. 访问应用
   打开浏览器访问：http://localhost:8502，使用设置的密码登录

服务管理命令

# 查看日志
docker compose -f docker-compose.single.yml logs -f

# 重启服务
docker compose -f docker-compose.single.yml restart

# 更新镜像
docker compose -f docker-compose.single.yml pull
docker compose -f docker-compose.single.yml up -d

# 停止服务
docker compose -f docker-compose.single.yml down

方案二：多容器生产部署

架构说明

多容器部署包含以下服务组件：

• surrealdb：数据库服务
• open_notebook：主应用服务（含API和Web界面）
• 后台任务处理器：负责 podcast 生成等耗时任务

部署步骤

1. 创建项目目录

mkdir open-notebook && cd open-notebook

2. 创建环境变量文件
   创建.env文件存储配置：

# 数据库配置
SURREAL_URL=ws://surrealdb:8000/rpc
SURREAL_USER=root
SURREAL_PASSWORD=root
SURREAL_NAMESPACE=open_notebook
SURREAL_DATABASE=production

# AI服务配置（至少需要一个API密钥）
OPENAI_API_KEY=your_openai_key_here
# ANTHROPIC_API_KEY=your_anthropic_key_here  # 可选

# 安全配置
OPEN_NOTEBOOK_PASSWORD=your_secure_password

3. 创建docker-compose配置文件
   创建docker-compose.yml文件：

version: '3.8'
services:
  surrealdb:
    image: surrealdb/surrealdb:latest
    ports:
      - "8000:8000"
    command: start --log warn --user root --pass root file:///mydata/database.db
    volumes:
      - ./surreal_data:/mydata
    restart: always
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3

  open_notebook:
    image: lfnovo/open_notebook:latest
    ports:
      - "8502:8502"  # Web界面
      - "5055:5055"  # API端口
    env_file:
      - .env
    volumes:
      - ./notebook_data:/app/data
    depends_on:
      surrealdb:
        condition: service_healthy
    restart: always

4. 启动服务

docker compose up -d

5. 验证部署
   访问http://localhost:8502，确认服务正常启动

服务管理命令

# 查看所有服务状态
docker compose ps

# 查看应用日志
docker compose logs -f open_notebook

# 单独重启数据库
docker compose restart surrealdb

# 备份数据
tar -czf backup-$(date +%Y%m%d).tar.gz notebook_data surreal_data

访问与初始配置

登录系统

1. 打开浏览器访问http://localhost:8502
2. 输入设置的密码（OPEN_NOTEBOOK_PASSWORD）
3. 首次登录后，系统会引导你完成初始设置

配置AI模型

1. 点击左侧导航栏的**⚙️ Settings**（设置）
2. 选择🤖 Models（模型）选项卡
3. 配置推荐模型：
   • 语言模型：gpt-4o-mini（平衡性能和成本）
   • 嵌入模型：text-embedding-3-small（用于搜索功能）
   • TTS模型：tts-1（用于播客生成）
4. 点击Save保存配置

创建第一个笔记本

1. 点击📒 Notebooks进入笔记本页面
2. 点击Create New Notebook按钮
3. 输入名称和描述，点击Create
4. 通过Add Source添加你的第一个内容源（网页链接、PDF或文本）

数据备份与迁移

数据备份

无论是单容器还是多容器部署，数据都存储在以下目录：

• notebook_data：存储笔记、上传文件等应用数据
• surreal_data（多容器）或surreal_single_data（单容器）：存储数据库文件

备份命令：

# 创建备份
tar -czf open-notebook-backup-$(date +%Y%m%d).tar.gz notebook_data surreal_data*

# 查看备份
ls -lh *.tar.gz

数据迁移

1. 在新环境创建相同的目录结构
2. 将备份文件复制到新环境
3. 解压备份文件：tar -xzf backup-file.tar.gz
4. 按照相同的部署步骤启动服务，数据会自动恢复

常见问题解决

服务无法启动

• 检查端口占用：确保8502、5055、8000端口未被占用

# 检查端口占用情况
sudo lsof -i :8502

• 检查日志：通过docker compose logs查看错误信息
• 资源不足：确保系统至少有1GB空闲内存

API密钥错误

• 确保API密钥正确，没有多余空格
• 检查OpenAI账户是否有可用余额
• 如使用代理，需配置HTTP_PROXY环境变量

数据访问问题

• 检查目录权限：ls -ld notebook_data surreal_data
• 确保Docker有权限读写数据目录
• 多容器部署时检查数据库连接是否正常

性能优化建议

• 对于低配置服务器，选择更小的模型（如gpt-3.5-turbo）
• 限制同时处理的任务数量
• 定期清理不需要的大文件和笔记

进阶配置与扩展

启用密码保护

在生产环境中，强烈建议启用密码保护：

OPEN_NOTEBOOK_PASSWORD=your_strong_password

密码应包含大小写字母、数字和特殊字符，长度至少8位

配置HTTPS（生产环境必备）

通过Nginx反向代理实现HTTPS：

1. 安装Nginx：sudo apt install nginx
2. 创建配置文件：/etc/nginx/sites-available/open-notebook
3. 配置SSL（可使用Let's Encrypt获取免费证书）
4. 启用站点：sudo ln -s /etc/nginx/sites-available/open-notebook /etc/nginx/sites-enabled/

集成其他AI提供商

除OpenAI外，还可配置其他AI提供商：

# Anthropic Claude
ANTHROPIC_API_KEY=your_anthropic_key

# Google Gemini
GOOGLE_API_KEY=your_google_key

# 本地模型（Ollama）
OLLAMA_API_BASE=http://your-ollama-ip:11434

总结与下一步

恭喜！你已成功部署并配置了open-notebook。通过Docker容器化方案，我们简化了部署流程，同时保证了系统的可维护性和可扩展性。

下一步建议

1. 探索高级功能：尝试使用🎙️ Podcasts功能生成音频内容
2. 学习快捷键：提高操作效率，如Ctrl+K快速搜索
3. 加入社区：在GitHub或Discord上分享使用体验和建议
4. 定期更新：通过docker compose pull保持系统最新

资源参考

• 官方文档：docs/deployment/index.md
• API参考：docs/development/api-reference.md
• 配置指南：setup_guide/DOCKER_SETUP_ADVANCED.md

如果觉得本指南有帮助，请点赞收藏，以便后续查阅和分享给更多需要的朋友！有任何问题，欢迎在项目GitHub仓库提交issue或参与讨论。