> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.alephant.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server.

# 部署快速入门

> 使用仓库内的 Docker Compose 引导脚本安装 OpenCore、验证服务，并完成可控升级。

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

## 前置条件

| 要求            | macOS 或 Linux                                  | Windows                                                               |
| ------------- | ---------------------------------------------- | --------------------------------------------------------------------- |
| Shell         | Bash 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 前阅读[部署模式](/opencore/deployment-modes)。

## 安装

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

### macOS 或 Linux

从仓库根目录执行：

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

### Windows

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

```powershell
Set-Location deployment\docker_compose
$env:INSTALL_PREFIX = "opencore_data"
.\install.ps1
```

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

| 操作        | macOS 或 Linux     | Windows         | 行为                     |
| --------- | ----------------- | --------------- | ---------------------- |
| 直接选择 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. 从运行安装脚本的目录检查生成的部署：

   ```bash
   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

```bash
INSTALL_PREFIX=opencore_data ./install.sh --shutdown
INSTALL_PREFIX=opencore_data ./install.sh
```

### Windows

```powershell
$env:INSTALL_PREFIX = "opencore_data"
.\install.ps1 -Shutdown
.\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>`。 |