OpenCore

部署快速入门

以 Markdown 格式查看

引导安装脚本会准备 Docker Compose 部署、生成本地环境文件、选择可用主机端口、拉取指定镜像并启动服务。请运行与宿主操作系统对应的脚本。

前置条件

要求macOS 或 LinuxWindows
ShellBash 3.2 或更高版本PowerShell 5 或更高版本
下载工具至少安装 curl 或 wget 其中之一受支持 PowerShell 版本自带的 Invoke-WebRequest
容器环境已运行的 Docker daemon 和 Docker Compose 2.24 或更高版本Docker Desktop 或其他支持 Linux 容器的 Docker 环境，以及 Docker Compose 2.24 或更高版本
Standard 建议资源10 GB Docker 内存和 32 GB 可用磁盘10 GB Docker 内存和 32 GB 可用磁盘
仓库可信的 OpenCore 仓库本地 checkout可信的 OpenCore 仓库本地 checkout

Unix 安装脚本还会使用 OpenSSL 生成本地 secret。请保护生成的 .env 文件，不要将其提交到源码仓库。

选择模式

模式服务支持的知识能力选择方式
Lite不启动 OpenSearch、Redis、模型服务或后台 worker连接器与 RAG 搜索不可用；对话、工具、文件上传、Projects、Agent knowledge 和代码解释器仍可使用接受交互选项 1，或在 Unix 使用 --lite、在 Windows 使用 -Lite
Standard启动完整的搜索与索引部署提供基于 OpenSearch 的搜索、连接器、索引和 RAG以交互方式运行并选择 2

交互默认值是 Lite。脚本没有 Standard 命令行开关，而 --no-prompt 或 -NoPrompt 会接受包括 Lite 在内的默认值。安装 Standard 时必须使用交互模式选择。

如果环境后续可能需要连接器或索引知识，请在选择 Lite 前阅读部署模式。

安装

通过 INSTALL_PREFIX 使用中性的安装目录；以下示例会在脚本运行目录下创建 opencore_data。

macOS 或 Linux

从仓库根目录执行：

$cd deployment/docker_compose
$chmod +x install.sh
$INSTALL_PREFIX=opencore_data ./install.sh

Windows

在 PowerShell 中从仓库根目录执行：

1Set-Location deployment\docker_compose
2$env:INSTALL_PREFIX = "opencore_data"
3.\install.ps1

安装脚本会询问部署模式与镜像 tag，为新部署创建 opencore_data/deployment/.env，启用 basic authentication，并生成本地 authentication secret。常用输入如下：

操作macOS 或 LinuxWindows行为
直接选择 Lite--lite-Lite跳过 Standard 搜索与索引服务
启用 Craft--include-craft-IncludeCraft启用 Craft；不能与 Lite 同时使用
复用已下载配置--local-Local要求安装目录内已存在预期配置文件
无提示接受默认值--no-prompt-NoPrompt使用包括 Lite 模式在内的默认值
只预览不修改--dry-run-DryRun输出安装计划后退出
显示诊断详情--verbose-ShowVerbose启用更详细的安装输出

在 Unix 中，--no-wait 会在容器启动后立即返回，而不是最多等待 600 秒完成健康检查。该返回结果不能证明所有服务都已就绪。

验证服务

  1. 从运行安装脚本的目录检查生成的部署：

    $cd opencore_data/deployment
    $docker compose ps

  2. 确认预期容器正在运行。Standard 应包含 OpenSearch 和搜索/索引 worker；Lite 会按设计省略这些服务。

  3. 打开安装脚本输出的 URL。脚本从 http://localhost:3000 开始选择端口；如果 3000 已被占用，会使用下一个可用端口。

  4. 打开该主机下的 /auth/signup 创建首个账户。第一个创建的用户会获得管理员权限。

升级

修改镜像 tag 前，先使用相同安装目录前缀停止当前部署。 运行以下命令前，请回到仓库 checkout 中的 deployment/docker_compose。

macOS 或 Linux

$INSTALL_PREFIX=opencore_data ./install.sh --shutdown
$INSTALL_PREFIX=opencore_data ./install.sh

Windows

1$env:INSTALL_PREFIX = "opencore_data"
2.\install.ps1 -Shutdown
3.\install.ps1

安装脚本发现已有 .env 后，选择 update、指定目标 tag，并再次选择原来的 Lite 或 Standard 模式。浮动 tag 会强制拉取并重建容器；启用下载时，固定 tag 还会让脚本获取与该版本匹配的部署配置。重启后请重新验证服务健康状态。

故障排查

现象检查项
安装脚本拒绝修改配置服务仍在运行。使用相同 INSTALL_PREFIX 调用脚本的 shutdown 选项，然后重新运行。
Docker Compose 无法解析 env_file将 Docker Compose 升级到 2.24 或更高版本。
预期页面不在 3000 端口查看安装脚本最后的输出；它会自动选择下一个可用主机端口。
Standard 知识能力缺失确认选择的是 Standard。Lite 不启动 OpenSearch、连接器或 RAG 搜索。
服务不健康在生成的部署目录运行 docker compose ps 和 docker compose logs <service>。