第 3 章 · 02 Docker 自托管

第 3 章 · 02 Docker 自托管

本节摘要:本节带你用 Docker 在本地跑起 OpenSEO。Docker 模式下,OpenSEO 使用 AUTH_MODE=local_noauth(关闭鉴权检查、本地管理员用户为 admin@localhost),因此只能放在你自己的、受保护的反代、隧道或私有网络之后;需要联网的自托管请改用 Cloudflare。我们走完克隆仓库、配置 .env、docker compose up 启动、设置 DATAFORSEO_API_KEY 的完整流程,并给出固定版本、自建镜像、常用命令与故障排查。读完本节,你能在本机访问 http://localhost:3001 用上完全自托管的 OpenSEO。

内容来源:原项目英文文档 web/content/docs/self-hosting/docker.md,汉化并套用体系化模板。

学习目标

阅读完本节,你应当能够:

1. 完成 Docker 自托管的快速启动(克隆、配 .env、起服务)。
2. 正确设置 DATAFORSEO_API_KEY 并访问本地实例。
3. 理解 Docker 模式的 安全约束(local_noauth,不可直接暴露公网)。
4. 掌握 固定版本、自建镜像、常用 docker compose 命令。
5. 排查 环境变量与容器重建 的常见问题。

一、前置条件

• Docker Desktop(或 Docker Engine + Docker Compose)。
• 一个 DataForSEO API key(获取方式见上一节「自托管总览」)。

默认的 compose.yaml 使用已发布的 GHCR 镜像:

ghcr.io/every-app/open-seo:latest
​

⚠️ 注意:安全前提:Docker 模式跑的是 AUTH_MODE=local_noauth——没有鉴权、本地管理员是 admin@localhost。绝不要把它直接暴露到公网。需要联网时,要么放在你自己加了鉴权的反代/隧道/私有网络后面,要么干脆改用 Cloudflare 自托管。

二、快速启动

克隆仓库,然后:

git clone https://github.com/every-app/open-seo.git
cd open-seo
cp .env.example .env
docker compose up -d
​

在 .env 里设置 DATAFORSEO_API_KEY,然后打开 http://localhost:<PORT>(默认 3001)。

工作机制:Docker Compose 会把 .env 的值传入容器,并且 compose.yaml 启用了 CLOUDFLARE_INCLUDE_PROCESS_ENV=true,让 Cloudflare Vite 运行时在本地自托管时能把这些值作为 Worker binding 读取。

三、可选环境变量

如果你把 Docker 放在反代或临时隧道后面,记得在重启前加上公网主机名:

ALLOWED_HOST=yourdomain.com docker compose up -d
​

也可以把它持久化到 .env。

💡 技巧:ALLOWED_HOST 是为反代/隧道场景准备的。如果你只是本机 localhost:3001 用,不需要设它;一旦你把它放到一个域名后面,就必须把这个域名设为 ALLOWED_HOST,否则 Vite preview 会拒绝请求。

四、遥测(Telemetry)

OpenSEO 收集匿名遥测,仅覆盖核心使用事件:每 5 分钟发送带聚合计数(安装数、用户数、项目数、功能使用)的心跳,绑定一个随机安装 ID;安装后头两小时内每 5 分钟一次,之后至多每天一次。不收集 URL、关键词、提示词、邮箱或 IP 推断的位置;空闲的安装什么都不发。

要关闭遥测,在 .env 里设 OPENSEO_TELEMETRY_DISABLED=1(或 DO_NOT_TRACK=1),然后:

docker compose up -d --force-recreate open-seo
​

五、固定到指定版本

在 .env 里设 OPEN_SEO_IMAGE,然后重启:

OPEN_SEO_IMAGE=ghcr.io/every-app/open-seo:v1.2.3
docker compose up -d
​

六、本地自建镜像

如果你在测试本地代码改动,构建并运行一个本地 tag:

docker build -f Dockerfile.selfhost -t open-seo:local .
OPEN_SEO_IMAGE=open-seo:local docker compose up -d
​

七、常用命令

⚠️ 注意:docker compose down -v 会删除数据卷(包括数据库),慎用——除非你想彻底重来。

八、故障排查:环境变量

确认 Docker Compose 用了预期的环境变量:

docker compose config
​

检查:

• AUTH_MODE=local_noauth 是否正确。
• DATAFORSEO_API_KEY 是否为「你的 DataForSEO 邮箱与 API 密码」按 email:password 格式的 Base64 编码值。

如果你改了 .env,需要 重建容器 让 Compose 重新应用:

docker compose up -d --force-recreate open-seo
​

💡 技巧:最常见的「启动了但数据查不到」问题,十有八九是 DATAFORSEO_API_KEY 格式不对或没生效。先用 docker compose config 看它有没有正确注入,再确认 Base64 编码内容确实是 email:password。

本节要点回顾

1. 快速启动:克隆 → cp .env.example .env → 填 DATAFORSEO_API_KEY → docker compose up -d → 访问 localhost:3001。
2. 安全前提:Docker 模式 local_noauth,只能放受保护的反代/隧道/私网后,不可直接公网。
3. 默认镜像:ghcr.io/every-app/open-seo:latest,可用 OPEN_SEO_IMAGE 改。
4. 可选变量:PORT、ALLOWED_HOST(反代时必设)、AUTH_MODE、OPEN_SEO_IMAGE。
5. 遥测:匿名聚合,可用 OPENSEO_TELEMETRY_DISABLED=1 或 DO_NOT_TRACK=1 关闭。
6. 固定版本:设 OPEN_SEO_IMAGE=...:v1.2.3 后重启。
7. 自建镜像:docker build -f Dockerfile.selfhost -t open-seo:local . 再用该 tag 起。
8. 改 env 必重建:用 docker compose up -d --force-recreate open-seo 让新值生效。

至此,P0 批次的 MCP 接入、Agent Skills 核心、自托管基础三条上手闭环已全部讲完。下一章(P1 批次)我们进入 SEO 方法论,以及更多进阶 Skill 与 Cloudflare 部署。