Octop Docker 部署完整指南：3 条命令在空服务器上跑起自托管 AI 助手，10 分钟通关

Octop Docker 部署完整指南：3 条命令在空服务器上跑起自托管 AI 助手，10 分钟通关

【免费下载链接】OctopA smarter, self-hosted AI assistant — multi-user, multi-agent.项目地址: https://gitcode.com/GitHub_Trending/oct/Octop

Octop 是一个支持 multi-user、multi-agent 的自托管 AI 助手：你在一台自己的服务器上部署它，就能拥有带 Web 控制台、可管理多个智能体、接入多家大模型 API 的私有 AI 平台。这篇文章带你用 Docker 从零把它跑起来——先花 10 分钟看到登录页，再回头拆开镜像构建、首次自初始化、Compose 编排这三层机制，最后收一份运维速查表。

先跑起来：3 条命令拿到登录页

别急着看原理，先让 Octop Docker 镜像构建和启动跑通。假设你有一台装好 Docker 的空服务器：

git clone https://gitcode.com/GitHub_Trending/oct/Octop cd Octop docker compose -f docker/docker-compose.yml up -d --build

--build会在启动前自动从源码构建镜像（构建上下文是仓库根目录，compose 文件里已经写好了，你不用管）。首次构建要下载前端依赖和 Python 依赖，视网络快慢大约 5~10 分钟。构建期间你可以另开一个终端盯着进度：

docker compose -f docker/docker-compose.yml logs -f

等日志出现启动信息后，浏览器打开http://localhost:8088，就能看到 Octop 的登录页或设置向导——到这里，部署链路已经走通了。

下面的内容回答两个问题：这个镜像是怎么被"炼"出来的？容器第一次启动时为什么能自己把数据库和账号准备好？

镜像是怎么构建出来的

.dockerignore 先把.git、tests、node_modules、本地.env等从构建上下文里裁掉，所以下载给 Docker 的源码包很干净，本机密钥也不会误入镜像。真正的构建定义在 docker/Dockerfile，它是一条两段流水线。

阶段一：node:20-slim 只负责编译前端

Octop 的 Web 控制台是一个 React + TypeScript 应用，源码在 dashboard/。第一阶段只做三件事，顺序很讲究：

1. 先拷锁文件再拷源码。Dockerfile 里先把package.json和package-lock.json拷进去执行npm ci，下一层才COPY dashboard/拷完整源码。因为依赖层只取决于锁文件，只要你不改依赖清单，这一层缓存永远命中，重复构建飞快；
2. 限制 Node 堆内存。NODE_MAX_OLD_SPACE_SIZE默认 2048MB，防止低内存构建机在 vite 打包时被 OOM 杀掉；如果你的构建机内存小于 4G，可以传--build-arg NODE_MAX_OLD_SPACE_SIZE=1024调低；
3. 产物落位。npm run build:docker（对应 dashboard/package.json 里的vite build）编译出静态文件，输出到/build/src/octop/dashboard，等待第二阶段取走。

阶段二：python:3.12-slim 只留运行时

第二阶段是真正跑服务的镜像，有三个设计值得你抄进自己的项目：

依赖层与代码层分开，缓存各管各的。Dockerfile 先COPY pyproject.toml uv.lock，用uv sync --frozen依据 uv.lock 精确安装锁定版本，之后才COPY src/拷代码。日常只改业务代码重新构建时，依赖层缓存照样命中，构建时间从分钟级缩到秒级。顺带一提，项目用 uv 而不是 pip——uv 的依赖解析比 pip 快一个数量级，配合--mount=type=cache,target=/root/.cache/uv缓存挂载，第二次安装几乎免费。

装完即拆。编译型 Python 依赖需要build-essential、libffi-dev这类编译工具链，但装完就apt-get purge掉，只保留运行时必需的curl（健康检查用）和fonts-noto-cjk（给浏览器自动化渲染中文用）。镜像越小，传输和启动越快，攻击面也越小。

健康检查内置。HEALTHCHECK每 30 秒请求一次GET /api/health（start-period=90s给首次启动留足预热时间，失败 3 次才判 unhealthy）。Docker 因此能自动感知容器"假死"，配合 Compose 里的restart: unless-stopped实现自愈——你半夜容器挂了，它自己会爬起来。

构建脚本替你处理了 BuildKit 和国内加速

不想手敲docker build，直接跑 docker/docker_build.sh：

bash docker/docker_build.sh # 构建 octop:latest bash docker/docker_build.sh my/octop:v1 # 自定义标签 bash docker/docker_build.sh octop:dev --no-cache # 透传任意 build 参数

脚本做了一件关键的事：强制DOCKER_BUILDKIT=1。前面提到的--mount=type=cache缓存挂载语法只有 BuildKit 才支持，npm、uv、apt 的下载产物因此能跨构建复用。

国内网络环境则追加四个环境变量，脚本会自动转成--build-arg注入构建：

PIP_INDEX_URL=https://mirrors.cloud.tencent.com/pypi/simple \ PIP_TRUSTED_HOST=mirrors.cloud.tencent.com \ NPM_REGISTRY=https://mirrors.cloud.tencent.com/npm/ \ APT_MIRROR=mirrors.cloud.tencent.com \ bash docker/docker_build.sh

容器第一次启动时如何自我初始化

跑通之后你会好奇：数据库文件谁建的？管理员账号谁建的？答案是 docker/docker-entrypoint.sh——它是容器的 ENTRYPOINT，可以理解为每次开机时的自检流程。

入口脚本如何防止弱密码反复重启

新手用 Docker 部署应用，最容易翻车的不是构建而是首次初始化。这个脚本的自检逻辑分四步：

1. 检测数据库文件。它检查/data/.octop/octop.db是否存在；不存在说明是全新数据卷，进入首次初始化分支。这里有个容易忽略的前置条件：容器内HOME被设为/data，所以数据目录统一落在/data/.octop，也就是你挂载的那个卷；
2. 密码策略校验。如果你通过OCTOP_DEFAULT_PASSWORD指定了初始密码，脚本先本地校验：至少 8 位、同时含字母和数字、不在内置的常见弱密码名单里（12345678、qwerty123、admin123这类都会被拒）；
3. 两条路，都不会把容器卡死。密码合格 → 执行octop init创建管理员账号，凭据以 600 权限写入卷内的credential.txt；密码没设置或被策略拒绝 →不自动建账号，改为生成一个随机向导口令写入/data/.octop/octop-login.txt，同时把说明写进credential.txt，然后正常启动服务、让你打开网页走设置向导自己定密码。这一设计专门针对"弱密码导致 init 失败 → 容器退出 → 重启 → 再失败"的死循环，保证容器绝不会因此反复重启；
4. 接管进程。最后exec octop run --host 0.0.0.0 --port 8088以 1 号进程运行，docker stop发来的终止信号能直达服务进程，优雅退出。

首次启动后进入 Web 控制台，你就可以配置大模型提供商、创建智能体，开始日常使用了：

凭据忘了怎么办

首次登录后，管理员账号密码在宿主机~/.octop/credential.txt（或命名卷里同名文件）里；向导口令在~/.octop/octop-login.txt。改密可以用 Web 头像菜单，也可以进容器执行：

docker exec -it octop octop user passwd --username admin

Compose 编排：端口、数据卷与 PostgreSQL 后端

docker/docker-compose.yml 把前面所有环节串成一条命令，有三个要点值得逐一看懂。

构建上下文是仓库根目录。compose 文件里context: ..加dockerfile: docker/Dockerfile，意思是"从仓库根目录打包构建上下文，用 docker/ 下的 Dockerfile"。前后端源码都在根目录，这是必须的。

数据卷把一切敏感状态放在宿主机。${OCTOP_DATA:-~/.octop}:/data/.octop这行卷挂载保证数据库、配置、上传文件全落在宿主机，容器删了重建数据不丢。

环境变量集中声明，可用 docker/.env 覆盖。OCTOP_PORT、OCTOP_DEFAULT_PASSWORD、数据库连接串、OPENAI_API_KEY/DASHSCOPE_API_KEY等都列在environment:里，你在docker/目录放一个.env文件即可覆盖。注意一个小细节：.env只参与 Compose 插值，只有列进environment:的变量才会真正进入容器。

想换 PostgreSQL 后端？Octop 默认用 SQLite（数据就在octop.db里），但 docs/adr/002-database-backends.md 描述了双后端设计。仓库自带 docker/docker-compose.postgres.yml：它单独起一个pgvector/pgvector:pg16实例（用户/库名默认octop），并在首次 initdb 时挂载执行 docker/postgres/init-vector.sql 自动创建 vector 扩展，不用你手动进数据库敲 SQL。起库之后在 Octop 侧配置OCTOP_DATABASE_DRIVER=postgresql和OCTOP_DATABASE_URL=postgresql://octop:octop@host.docker.internal:5432/octop即可切换。

新手最容易踩的 4 个坑

现象：docker compose up 报找不到构建文件

原因：你在docker/目录里跑了裸docker compose up。context: ..是相对路径，裸跑时 Compose 找不到docker-compose.yml，或者以docker/为上下文导致构建缺源码。

解法：始终在仓库根目录执行，并显式指定文件：

docker compose -f docker/docker-compose.yml up -d --build

现象：端口被占用，提示 port is already allocated

原因：Octop 默认监听 8088，如果这台机器上别的服务已经占了它，容器会起不来。

解法：通过环境变量换端口，映射两端同时变：

OCTOP_PORT=9090 docker compose -f docker/docker-compose.yml up -d

之后访问http://localhost:9090。

现象：打开页面没有登录入口，卡在设置向导

原因：这不是故障，是预期行为——你要么没设置OCTOP_DEFAULT_PASSWORD，要么设置的密码被策略拒绝（过短、缺字母或数字、常见弱密码），脚本按设计不自动建账号。

解法：取出向导口令，在页面里完成初始设置：

docker exec -it octop cat /data/.octop/octop-login.txt

向导里由你自己选择管理员用户名和密码，比塞一个默认账号安全得多。

现象：docker rm 之后登录不了，数据全没了

原因：docker run时忘了挂载卷，数据写进了容器可写层，随容器一起删除；或者用了命名卷但执行了docker volume rm。

解法：优先用 Compose（默认挂~/.octop）；手动docker run时务必带上-v ~/.octop:/data/.octop和-e HOME=/data。部署后养成习惯，定期备份宿主机上这个目录。

💡 镜像默认绑定0.0.0.0监听，如果服务器有公网 IP，暴露到公网前请一定配置反向代理 + TLS，并在首次登录后立即修改管理员密码。

运维速查：部署后该记住的命令

把 Octop 的 Docker 方案浓缩成一句话：多阶段构建让镜像小而精，缓存分层让构建快，入口脚本让首次启动不翻车。掌握这套"构建 → 启动 → 编排"的拆解方式，你手里的任何自托管项目都能照方抓药。

【免费下载链接】OctopA smarter, self-hosted AI assistant — multi-user, multi-agent.项目地址: https://gitcode.com/GitHub_Trending/oct/Octop