Octop Docker 部署完整指南3 条命令在空服务器上跑起自托管 AI 助手10 分钟通关【免费下载链接】OctopA smarter, self-hosted AI assistant — multi-user, multi-agent.项目地址: https://gitcode.com/GitHub_Trending/oct/OctopOctop 是一个支持 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/。第一阶段只做三件事顺序很讲究先拷锁文件再拷源码。Dockerfile 里先把package.json和package-lock.json拷进去执行npm ci下一层才COPY dashboard/拷完整源码。因为依赖层只取决于锁文件只要你不改依赖清单这一层缓存永远命中重复构建飞快限制 Node 堆内存。NODE_MAX_OLD_SPACE_SIZE默认 2048MB防止低内存构建机在 vite 打包时被 OOM 杀掉如果你的构建机内存小于 4G可以传--build-arg NODE_MAX_OLD_SPACE_SIZE1024调低产物落位。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 快一个数量级配合--mounttypecache,target/root/.cache/uv缓存挂载第二次安装几乎免费。装完即拆。编译型 Python 依赖需要build-essential、libffi-dev这类编译工具链但装完就apt-get purge掉只保留运行时必需的curl健康检查用和fonts-noto-cjk给浏览器自动化渲染中文用。镜像越小传输和启动越快攻击面也越小。健康检查内置。HEALTHCHECK每 30 秒请求一次GET /api/healthstart-period90s给首次启动留足预热时间失败 3 次才判 unhealthy。Docker 因此能自动感知容器假死配合 Compose 里的restart: unless-stopped实现自愈——你半夜容器挂了它自己会爬起来。构建脚本替你处理了 BuildKit 和国内加速不想手敲docker build直接跑 docker/docker_build.shbash 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_BUILDKIT1。前面提到的--mounttypecache缓存挂载语法只有 BuildKit 才支持npm、uv、apt 的下载产物因此能跨构建复用。国内网络环境则追加四个环境变量脚本会自动转成--build-arg注入构建PIP_INDEX_URLhttps://mirrors.cloud.tencent.com/pypi/simple \ PIP_TRUSTED_HOSTmirrors.cloud.tencent.com \ NPM_REGISTRYhttps://mirrors.cloud.tencent.com/npm/ \ APT_MIRRORmirrors.cloud.tencent.com \ bash docker/docker_build.sh容器第一次启动时如何自我初始化跑通之后你会好奇数据库文件谁建的管理员账号谁建的答案是 docker/docker-entrypoint.sh——它是容器的 ENTRYPOINT可以理解为每次开机时的自检流程。入口脚本如何防止弱密码反复重启新手用 Docker 部署应用最容易翻车的不是构建而是首次初始化。这个脚本的自检逻辑分四步检测数据库文件。它检查/data/.octop/octop.db是否存在不存在说明是全新数据卷进入首次初始化分支。这里有个容易忽略的前置条件容器内HOME被设为/data所以数据目录统一落在/data/.octop也就是你挂载的那个卷密码策略校验。如果你通过OCTOP_DEFAULT_PASSWORD指定了初始密码脚本先本地校验至少 8 位、同时含字母和数字、不在内置的常见弱密码名单里12345678、qwerty123、admin123这类都会被拒两条路都不会把容器卡死。密码合格 → 执行octop init创建管理员账号凭据以 600 权限写入卷内的credential.txt密码没设置或被策略拒绝 →不自动建账号改为生成一个随机向导口令写入/data/.octop/octop-login.txt同时把说明写进credential.txt然后正常启动服务、让你打开网页走设置向导自己定密码。这一设计专门针对弱密码导致 init 失败 → 容器退出 → 重启 → 再失败的死循环保证容器绝不会因此反复重启接管进程。最后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 adminCompose 编排端口、数据卷与 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_DRIVERpostgresql和OCTOP_DATABASE_URLpostgresql://octop:octophost.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_PORT9090 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并在首次登录后立即修改管理员密码。运维速查部署后该记住的命令场景命令跟踪实时日志docker logs -f octop手动健康探测curl http://localhost:8088/api/health查看容器健康状态docker inspect --format {{.State.Health.Status}} octop进容器查版本docker exec -it octop octop --version改管理员密码docker exec -it octop octop user passwd --username admin拉取新代码重建docker compose -f docker/docker-compose.yml up -d --build停止并移除容器docker compose -f docker/docker-compose.yml down把 Octop 的 Docker 方案浓缩成一句话多阶段构建让镜像小而精缓存分层让构建快入口脚本让首次启动不翻车。掌握这套构建 → 启动 → 编排的拆解方式你手里的任何自托管项目都能照方抓药。【免费下载链接】OctopA smarter, self-hosted AI assistant — multi-user, multi-agent.项目地址: https://gitcode.com/GitHub_Trending/oct/Octop创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/14 5:47:34 · 阅读 1.2k 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/OctopOctop 是一个支持 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/。第一阶段只做三件事顺序很讲究先拷锁文件再拷源码。Dockerfile 里先把package.json和package-lock.json拷进去执行npm ci下一层才COPY dashboard/拷完整源码。因为依赖层只取决于锁文件只要你不改依赖清单这一层缓存永远命中重复构建飞快限制 Node 堆内存。NODE_MAX_OLD_SPACE_SIZE默认 2048MB防止低内存构建机在 vite 打包时被 OOM 杀掉如果你的构建机内存小于 4G可以传--build-arg NODE_MAX_OLD_SPACE_SIZE1024调低产物落位。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 快一个数量级配合--mounttypecache,target/root/.cache/uv缓存挂载第二次安装几乎免费。装完即拆。编译型 Python 依赖需要build-essential、libffi-dev这类编译工具链但装完就apt-get purge掉只保留运行时必需的curl健康检查用和fonts-noto-cjk给浏览器自动化渲染中文用。镜像越小传输和启动越快攻击面也越小。健康检查内置。HEALTHCHECK每 30 秒请求一次GET /api/healthstart-period90s给首次启动留足预热时间失败 3 次才判 unhealthy。Docker 因此能自动感知容器假死配合 Compose 里的restart: unless-stopped实现自愈——你半夜容器挂了它自己会爬起来。构建脚本替你处理了 BuildKit 和国内加速不想手敲docker build直接跑 docker/docker_build.shbash 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_BUILDKIT1。前面提到的--mounttypecache缓存挂载语法只有 BuildKit 才支持npm、uv、apt 的下载产物因此能跨构建复用。国内网络环境则追加四个环境变量脚本会自动转成--build-arg注入构建PIP_INDEX_URLhttps://mirrors.cloud.tencent.com/pypi/simple \ PIP_TRUSTED_HOSTmirrors.cloud.tencent.com \ NPM_REGISTRYhttps://mirrors.cloud.tencent.com/npm/ \ APT_MIRRORmirrors.cloud.tencent.com \ bash docker/docker_build.sh容器第一次启动时如何自我初始化跑通之后你会好奇数据库文件谁建的管理员账号谁建的答案是 docker/docker-entrypoint.sh——它是容器的 ENTRYPOINT可以理解为每次开机时的自检流程。入口脚本如何防止弱密码反复重启新手用 Docker 部署应用最容易翻车的不是构建而是首次初始化。这个脚本的自检逻辑分四步检测数据库文件。它检查/data/.octop/octop.db是否存在不存在说明是全新数据卷进入首次初始化分支。这里有个容易忽略的前置条件容器内HOME被设为/data所以数据目录统一落在/data/.octop也就是你挂载的那个卷密码策略校验。如果你通过OCTOP_DEFAULT_PASSWORD指定了初始密码脚本先本地校验至少 8 位、同时含字母和数字、不在内置的常见弱密码名单里12345678、qwerty123、admin123这类都会被拒两条路都不会把容器卡死。密码合格 → 执行octop init创建管理员账号凭据以 600 权限写入卷内的credential.txt密码没设置或被策略拒绝 →不自动建账号改为生成一个随机向导口令写入/data/.octop/octop-login.txt同时把说明写进credential.txt然后正常启动服务、让你打开网页走设置向导自己定密码。这一设计专门针对弱密码导致 init 失败 → 容器退出 → 重启 → 再失败的死循环保证容器绝不会因此反复重启接管进程。最后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 adminCompose 编排端口、数据卷与 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_DRIVERpostgresql和OCTOP_DATABASE_URLpostgresql://octop:octophost.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_PORT9090 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并在首次登录后立即修改管理员密码。运维速查部署后该记住的命令场景命令跟踪实时日志docker logs -f octop手动健康探测curl http://localhost:8088/api/health查看容器健康状态docker inspect --format {{.State.Health.Status}} octop进容器查版本docker exec -it octop octop --version改管理员密码docker exec -it octop octop user passwd --username admin拉取新代码重建docker compose -f docker/docker-compose.yml up -d --build停止并移除容器docker compose -f docker/docker-compose.yml down把 Octop 的 Docker 方案浓缩成一句话多阶段构建让镜像小而精缓存分层让构建快入口脚本让首次启动不翻车。掌握这套构建 → 启动 → 编排的拆解方式你手里的任何自托管项目都能照方抓药。【免费下载链接】OctopA smarter, self-hosted AI assistant — multi-user, multi-agent.项目地址: https://gitcode.com/GitHub_Trending/oct/Octop创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考