教程 / 安装 / Docker

方式三：Docker 安装

适合容器化部署、一键启动与生产环境运维。

一、环境要求

在 Ubuntu 22.04 LTS Server 上通过 Docker Compose 标准模式一键安装 OpenAkita。

项目	说明
系统	Ubuntu 22.04 LTS Server（已联网）
权限	具备 `sudo` 的普通用户
API Key	至少配置一个大模型提供商密钥
磁盘	推荐20 GB 及以上

二、安装步骤

1. 安装 Docker 和 Docker Compose

国内访问 download.docker.com 较慢，建议使用阿里云 Docker CE 源。

# 1. 安装依赖
sudo apt update
sudo apt install -y ca-certificates curl gnupg lsb-release

# 2. 添加 Docker GPG 密钥 (阿里云镜像)
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://mirrors.aliyun.com/docker-ce/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# 3. 设置 Docker 稳定版仓库 (阿里云镜像)
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://mirrors.aliyun.com/docker-ce/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 4. 安装 Docker Engine 和 Docker Compose Plugin
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# 5. 验证安装
sudo docker run hello-world
sudo docker compose version

2. 配置 Docker 镜像加速 (可选但推荐)

若拉取镜像超时，建议配置国内镜像加速。

sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json <<-'EOF'
{
  "registry-mirrors": [
    "https://docker.1ms.run",
    "https://docker.m.daocloud.io"
  ]
}
EOF

sudo systemctl daemon-reload
sudo systemctl restart docker

三、部署 OpenAkita

3.1 克隆项目

cd ~
# 完整克隆
git clone https://github.com/OpenAkita/OpenAkita.git
# 或：浅克隆（更快，只要最新版）
git clone --depth 1 https://github.com/openakita/openakita.git
cd OpenAkita

3.2 配置环境变量

复制示例配置文件并根据需要修改：

cp examples/.env.example .env
# 使用 nano 或 vim 编辑 .env 文件
nano .env

注意：请至少配置 LLM_API_KEY 或其他必要的模型提供商密钥。

DASHSCOPE_API_KEY=sk-你的密钥

复制大模型端点配置文件并根据需要修改:

cp data/llm_endpoints.json.example data/llm_endpoints.json
nano data/llm_endpoints.json

通义千问示例（主端点）：

在 endpoints 数组中加入或修改为类似配置：

"endpoints": [
    {
      "name": "dashscope-qwen3.5-plus",
      "provider": "dashscope",
      "api_type": "openai",
      "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
      "model": "qwen3.5-plus",
      "priority": 10,
      "max_tokens": 0,
      "context_window": 200000,
      "timeout": 180,
      "rpm_limit": 0,
      "capabilities": [
        "text",
        "vision",
        "video",
        "tools",
        "thinking"
      ]
    }
  ]

3.3 启动服务

同步最新代码

git pull --rebase

使用 Docker Compose 后台启动所有服务（前端、后端、数据库、向量库等）：

# 首次构建（不要用 --no-cache，否则会重复慢速 apt/npm，耗时很长）
sudo docker compose build
# 启动
sudo docker compose up -d

补充：当前版本在 docker compose build 时，如果出现报错，可以构建前自动打补丁：

cd ~/openakita

grep -q 'providers.json /app/src/openakita/llm/registries/providers.json' Dockerfile || \
sed -i '/RUN npm ci/a COPY src/openakita/llm/registries/providers.json /app/src/openakita/llm/registries/providers.json' Dockerfile

# 确认补丁已写入
grep -n 'providers.json' Dockerfile

应看到类似:

7:COPY src/openakita/llm/registries/providers.json /app/src/openakita/llm/registries/providers.json

然后再执行:

sudo docker compose build
sudo docker compose up -d

3.4 查看日志

确认服务启动正常：

sudo docker compose logs -f

按 Ctrl+C 退出日志查看。

补充：构建成功后，若容器状态为 Restarting，日志出现：

Error: No such option: --host

原因：镜像默认 CMD 为 openakita serve --host 0.0.0.0 --port 18900，但当前版本（如 1.27.12）的 serve 子命令不支持 --host / --port，应通过环境变量 API_HOST、API_PORT 配置（docker-compose.yml 已包含）。

方案 A：修改 docker-compose.yml（推荐，无需重新 build）

编辑 docker-compose.yml，在 openakita: 服务下、container_name: 附近增加：

command: ["serve"]

或使用命令自动插入：

cd ~/openakita
grep -q 'command: \["serve"\]' docker-compose.yml || \
sed -i '/container_name: openakita/a\    command: ["serve"]' docker-compose.yml 
sudo docker compose up -d

方案 B：修改 Dockerfile（长期）

sed -i 's/CMD \["serve", "--host", "0.0.0.0", "--port", "18900"\]/CMD ["serve"]/' Dockerfile
# 然后需要重新 build
sudo docker compose build

3.5 验证与健康检查

# 容器状态
sudo docker compose ps

# 健康检查（两个路径都试一下）
sudo curl http://127.0.0.1:18900/health
sudo curl http://127.0.0.1:18900/api/health

四、访问 OpenAkita

部署完成后，在浏览器中访问：

地址：http://<虚拟机IP>:18900（默认端口，具体见 .env 中的 FRONTEND_PORT）

若密码遗忘，可以重新设置密码

export OPENAKITA_WEB_PASSWORD='<你的新密码>'

五、常用管理命令

停止服务

sudo docker compose down

重启服务

sudo docker compose restart

更新版本

git pull
sudo docker compose up -d --build

查看容器状态

sudo docker compose ps

六、故障排查

端口冲突

如果对应端口被占用，请在 .env 中修改 FRONTEND_PORT 和 BACKEND_PORT，然后重启。

权限问题

如果遇到 Permission denied，请确保当前用户在 docker 组中：

sudo usermod -aG docker $USER
newgrp docker

内存不足

OpenAkita 包含多个组件，建议服务器至少拥有 4GB+ 内存。