OpenSEO Docker 自托管完全指南：本地一键启动、环境变量配置与反向代理实战

OpenSEO Docker 自托管完全指南本地一键启动、环境变量配置与反向代理实战【免费下载链接】open-seoOpen source alternative to Semrush and Ahrefs项目地址: https://gitcode.com/GitHub_Trending/op/open-seo本文基于 OpenSEO 官方自托管文档 web/content/docs/self-hosting/docker.md 与仓库内compose.yaml、Dockerfile.selfhost、docker-entrypoint.sh 等源码展开系统讲解如何用 Docker Compose 在本机或私有网络运行开源 SEO 工具 OpenSEO涵盖前置条件、快速启动、环境变量矩阵、Telemetry 隐私控制、镜像版本钉扎、自建镜像以及健康检查与排障的完整链路。OpenSEO 是 Semrush / Ahrefs 的开源替代品支持两种自托管路径面向个人本机的Docker 模式本文主题与面向公网多设备的Cloudflare 模式。Docker 模式以一条docker compose up -d即可拉起完整应用自带持久化数据卷、启动预检preflight、条件式构建缓存与健康检查。读完本文你将掌握如何用官方 GHCR 镜像快速启动、如何理解compose.yaml中每个环境变量的作用、如何把服务安全地放到反向代理或隧道之后、如何按需关闭遥测以及如何借助/api/health与启动日志完成分钟级故障定位。一、Docker 模式的定位本地无鉴权部署在 Docker 模式下OpenSEO 使用AUTH_MODElocal_noauth不做任何鉴权检查并注入一个本地管理员用户adminlocalhost。这意味着容器本身没有任何登录门槛——官方文档与源码都反复强调只能将服务暴露在你自己的鉴权反向代理、隧道或私有网络之后如需面向公网的自托管请改用 Cloudflare 模式。这一约束在源码层面有明确体现。src/lib/selfhost-preflight.ts的checkAuthMode对local_noauth的检查结果直接输出警告文案local_noauth — no auth, single admin user. Do not expose publicly without your own auth in front.无鉴权、单一管理员用户未在前置加鉴权前请勿公网暴露。而 compose.yaml 的端口映射也默认只绑定回环地址ports: - 127.0.0.1:${PORT:-3001}:${PORT:-3001}即默认只监听127.0.0.1外部网络无法直接访问——这是一个默认安全的设计。若要通过公网访问正确的姿势是搭配反向代理或隧道并通过ALLOWED_HOST声明允许的对外主机名详见下文。二、前置条件在开始之前请确认以下两项Docker 环境Docker DesktopmacOS / Windows或 Linux 上的 Docker Engine Docker Compose 插件。DataForSEO API KeyOpenSEO 依赖 DataForSEO 拉取 SEO 数据排名、反链、站点审计等。这不是 DataForSEO 控制台里显示的 API Key而是email:password的 Base64 编码值。申请步骤见 docs/DATAFORSEO_API_KEY.md在 DataForSEO 的 API Access 页面点击 Send by email复制标记为 Base64 的那一组较长的凭据即可。新账户自带 $1 免费额度最低充值 $50。三、快速启动五步跑起 OpenSEO克隆仓库后按如下步骤操作git clone https://github.com/every-app/open-seo.git cd open-seo cp .env.example .env注意仓库根目录下的 .env.example 是 Docker 自托管的官方模板web/子项目是营销站点不要混淆。Compose 通过env_file: .env把.env中每一个变量都注入容器因此cp .env.example .env这一步是必需的前置动作——compose.yaml 中注释明确写道Compose errors if .env is missing; the quickstartscp .env.example .envcreates it..env缺失时 Compose 直接报错。在.env中填入DATAFORSEO_API_KEY值为email:password的 Base64 编码然后启动docker compose up -d打开http://localhost:PORT默认端口3001即可使用。首次启动耗时 12 分钟容器启动时会在内部先跑迁移和 Vite 生产构建原因见下文启动流程一节。用以下命令跟进进度docker compose logs -f可选的常用环境变量变量默认值说明PORT3001应用对外端口同时影响容器端口映射与vite preview监听端口ALLOWED_HOST空允许访问的单个反向代理主机名Vite preview 的 host 白名单AUTH_MODElocal_noauth已在 compose 中固定为本地无鉴权模式OPEN_SEO_IMAGEghcr.io/every-app/open-seo:latest使用的镜像 tagOPENROUTER_API_KEY空启用 AI 功能SAM应用内 SEO Agent见.env.example注释放在反向代理 / 隧道之后Docker 自托管运行在无应用鉴权状态因此官方建议仅在你自己的鉴权反向代理、隧道或私有网络之后暴露。同时在重启前声明对外主机名ALLOWED_HOSTyourdomain.com docker compose up -d也可以把ALLOWED_HOST持久化写入.env。如果不设置通过非 localhost 域名访问时vite preview会返回 Blocked request 拦截页。这个行为在 src/lib/selfhost-preflight.ts 的启动预检中有对应提示Not set — only localhost access will work. Behind a reverse proxy or tunnel, set ALLOWED_HOSTyourdomain.com or requests are blocked with Vites Blocked request page.四、compose.yaml 逐项解读每个配置在做什么官方 compose.yaml 是理解 Docker 模式行为的最佳入口逐段拆解如下services: open-seo: image: ${OPEN_SEO_IMAGE:-ghcr.io/every-app/open-seo:latest} restart: unless-stoppedimage默认拉取 GHCR 官方镜像ghcr.io/every-app/open-seo:latest可用OPEN_SEO_IMAGE覆盖用于钉扎版本或使用本地自建镜像。restart: unless-stopped容器异常退出时自动重启除非被手动停止。env_file: - .envenv_file把.env中全部变量注入容器这是OPENROUTER_API_KEY等未显式列出的变量也能生效的关键。显式environment:列表中列出的变量优先。environment: - CLOUDFLARE_INCLUDE_PROCESS_ENVtrue - PORT${PORT:-3001} - ALLOWED_HOST${ALLOWED_HOST:-} - AUTH_MODElocal_noauth - OPENSEO_TELEMETRY_DISABLED${OPENSEO_TELEMETRY_DISABLED:-} - DO_NOT_TRACK${DO_NOT_TRACK:-} - DATAFORSEO_API_KEY${DATAFORSEO_API_KEY} - OPENROUTER_API_KEY${OPENROUTER_API_KEY:-} - GOOGLE_CLIENT_ID${GOOGLE_CLIENT_ID:-} - GOOGLE_CLIENT_SECRET${GOOGLE_CLIENT_SECRET:-} - BETTER_AUTH_SECRET${BETTER_AUTH_SECRET:-} - OPENROUTER_MODEL${OPENROUTER_MODEL:-} - VITE_SHOW_DEVTOOLSfalseCLOUDFLARE_INCLUDE_PROCESS_ENVtrueDocker 本地自托管的必需项让基于cloudflare:workers的运行时绑定能读取到进程环境变量OpenSEO 底层跑在 workerd 上。AUTH_MODElocal_noauth写死为本地无鉴权模式与文档一致。DATAFORSEO_API_KEY必填缺失时所有 SEO 数据功能不可用预检只给 warn 不阻断启动。OPENROUTER_API_KEY/OPENROUTER_MODEL可选用于启用 SAM 等 AI 功能compose 中该变量出现了两次注释为Optional: AI features (the SAM agent)与Optional: AI features (SAM, the in-app SEO agent)后者还额外暴露了模型选择。GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRET/BETTER_AUTH_SECRET可选用于 Google Search Console 集成BETTER_AUTH_SECRET还承担加密存储 OAuth Token 的职责要求至少 32 字符见 src/shared/selfhost-checks.ts 中MIN_BETTER_AUTH_SECRET_LENGTH 32。GSC 完整配置见 docs/SELF_HOSTING_GOOGLE_SEARCH_CONSOLE.md。VITE_SHOW_DEVTOOLSfalse关闭生产环境的开发工具开关。ports: - 127.0.0.1:${PORT:-3001}:${PORT:-3001} volumes: - open_seo_data:/app/.wrangler volumes: open_seo_data:ports仅绑定127.0.0.1默认不对外网开放。volumes命名卷open_seo_data挂载到/app/.wrangler持久化 D1 本地数据库等运行时数据——这是数据不随容器销毁而丢失的保障docker compose down不会清除它除非显式加-v。.env.example 中的其他可选变量除上面表格列出的之外.env.example 还完整列举了三种鉴权模式下的可选配置Docker 模式下仅local_noauth生效TEAM_DOMAIN/POLICY_AUDcloudflare_access模式Cloudflare Access JWT 校验所需Docker 模式不需要BETTER_AUTH_URL、POSTHOG_PUBLIC_KEY、POSTHOG_HOST、LOOPS_API_KEY及三个LOOPS_TRANSACTIONAL_*模板 IDhosted模式Better Auth 邮箱/密码 组织所需。五、Telemetry采集了什么如何关闭OpenSEO 默认采集匿名化遥测用于统计核心使用事件。官方文档给出如下边界源码 src/server/lib/self-host-telemetry.ts 与之完全对应心跳heartbeat携带聚合计数安装数、用户数、项目数、功能使用情况绑定一个随机生成的安装 IDinstallId: crypto.randomUUID()存于telemetryState表。发送节奏安装后前两小时内每 5 分钟一次ONBOARDING_HEARTBEAT_INTERVAL_MS 5 * 60 * 1000之后最多每天一次DAILY_HEARTBEAT_INTERVAL_MS 24 * 60 * 60 * 1000。还包括失败的 setup 检查名称与状态形如dataforseo:error的可枚举键值对绝不含具体值或错误消息disableGeoip: true表明不启用 IP 地理位置解析。不采集URL、关键词、提示词、邮箱、IP 派生位置。空闲安装无活跃心跳不发送任何数据。只有生产构建import.meta.env.MODE production才上报vite dev、vitest、预览部署均被排除见isNonProductionBuild()。关闭方式在.env中设置OPENSEO_TELEMETRY_DISABLED1或DO_NOT_TRACK1然后重建容器使其生效docker compose up -d --force-recreate open-seo语义细节可参考 src/shared/selfhost-checks.ts 的isTelemetryOptOutValue除了显式的0/false/no/off之外任何值都视为关闭默认向隐私倾斜fail toward privacy。六、钉扎镜像版本从 latest 到确定版本生产或长期运行建议固定镜像 tag避免latest漂移带来意外变更。在.env中设置后重启即可OPEN_SEO_IMAGEghcr.io/every-app/open-seo:v1.2.3 docker compose up -d重启后可用docker compose ps或docker image inspect确认实际运行的镜像。七、构建自己的本地镜像验证代码改动如果你在测试本地代码改动可以用仓库自带的 Dockerfile.selfhost 构建本地 tag然后以OPEN_SEO_IMAGE覆盖默认镜像docker build -f Dockerfile.selfhost -t open-seo:local . OPEN_SEO_IMAGEopen-seo:local docker compose up -d关于 Dockerfile 的几个实现细节有助于理解镜像行为基于node:22完整镜像保证 workerd 出站 HTTPS 有可用的 CA 信任库启用 pnpm 10.30.1EXPOSE 3001与 compose 的默认端口一致HEALTHCHECK每 30s 探测一次http://127.0.0.1:PORT/api/health--start-period300s覆盖迁移 启动期 Vite 构建的耗时CMD [sh, docker-entrypoint.sh]把完整启动流程交给 docker-entrypoint.sh。容器启动流程docker-entrypoint.sh阅读 docker-entrypoint.sh 可以还原容器每次启动的真实步骤打印遥测提示并说明关闭方式运行启动预检pnpm exec tsx scripts/selfhost-preflight.ts——在耗时步骤之前校验环境配置错误会在数秒内以明确修复建议失败退出而不是在数分钟构建后才暴露详见 scripts/selfhost-preflight.ts执行数据库迁移pnpm run db:migrate:local条件式构建对影响构建产物的环境变量VITE_前缀变量、AUTH_MODE、POSTHOG_PUBLIC_KEY等做指纹sha256sum与上次构建写入的指纹标记比对一致则直接复用已有构建产物否则执行pnpm run build并写入新指纹——这正是换镜像或改构建相关环境变量才重新构建的机制也是首次启动耗时 12 分钟的原因启动服务vite preview --host 0.0.0.0 --port ${PORT:-3001}。由于 Vite 构建会把带envPrefix前缀的客户端环境变量内联进产物所以构建必须放在容器启动时执行而不能打包进镜像——指纹机制保证了这种启动时构建的开销只在必要时发生。八、常用运维命令速查场景命令修改环境变量后重启服务docker compose up -d open-seo拉取最新镜像并重启docker compose pull docker compose up -d停止服务docker compose down强制重建容器重新应用.envdocker compose up -d --force-recreate open-seo跟进启动日志docker compose logs -f九、健康检查与排障健康状态怎么看启动日志预检结果--- OpenSEO self-host preflight ---会在构建前打印在docker compose logs中[ ok ]/[info]/[warn]/[FAIL]四档分别对应通过、提示、降级、致命。/api/health运行后无需鉴权即可访问hosted 模式下仅返回{status:ok}。该端点复用与启动预检同一套检查逻辑getSelfHostSetupStatus返回按功能划分的配置与数据库状态任一 check 为error时顶层status为issues否则为ok。实现见 src/routes/api/health.ts注释明确它是为自托管者准备的诊断入口——container is up but misconfigured 一条 curl 即可定位。docker compose ps查看容器运行状态与 HEALTHCHECK 结果。环境变量排查三板斧核对实际生效值docker compose config输出 Compose 解析后的最终配置确认AUTH_MODElocal_noauth、DATAFORSEO_API_KEY等已按预期注入。核对 DataForSEO 凭据格式DATAFORSEO_API_KEY必须是email:password的 Base64 编码值不是DataForSEO 控制台里显示的 API Key。looksLikeDataForSeoKeysrc/shared/selfhost-checks.ts的实现是解码后查找冒号——这是最常踩的坑可用一条命令本地验证printf email:password | base64预检脚本对格式不对的 key 会给出 warndoes not decode as base64 of login:password。改了.env必须重建容器docker compose up -d --force-recreate open-seo因为只有重建而不是仅重启才会让 Compose 重新读取.env并应用全部变更。预检检查项一览Docker 启动预检覆盖五类检查见 src/lib/selfhost-preflight.tsAUTH_MODE非法值直接[FAIL]退出local_noauth通过并附带勿公网直连提醒hosted模式要求BETTER_AUTH_URL、BETTER_AUTH_SECRET、GOOGLE_CLIENT_ID、GOOGLE_CLIENT_SECRET四项齐备未设置时默认cloudflare_access需提供TEAM_DOMAIN与POLICY_AUD。DATAFORSEO_API_KEY未设置为[warn]SEO 功能不可用设置了但格式不对为[warn]正常为[ok]。Search ConsoleGSC只配了GOOGLE_CLIENT_ID或GOOGLE_CLIENT_SECRET之一、或BETTER_AUTH_SECRET不足 32 字符时为[warn]未配置则为[info]。AI 功能OPENROUTER_API_KEY未设置时提示 SAM 被禁用可选。运行时ALLOWED_HOST未设置时提示仅 localhost 可访问并提示Rank-tracking schedules do not run in Docker mode — trigger checks from the Rank Tracking page.Docker 模式不运行定时排名检查需要在排名追踪页面手动触发检查。预检失败存在[FAIL]项时进程以非零码退出、什么都不启动此时会发送一个仅含失败检查名的匿名信标self_host.preflight_failed不影响启动逻辑见 scripts/selfhost-preflight.ts。预检通过后才会进入迁移与构建阶段。十、总结与进一步阅读Docker 模式是 OpenSEO 自托管成本最低、上手最快的路径一条 Compose 命令即可在本机或私有网络获得完整的 SEO 工具链预检、条件构建、健康检查与匿名遥测共同构成了快速失败、可诊断、可回溯的运维体验。需要牢记的三条红线是默认无鉴权只能放私有网络/反向代理之后、DATAFORSEO_API_KEY是email:password的 Base64、改.env必须--force-recreate。如需继续深入仓库内还提供了公网级自托管方案Cloudflare 自托管指南以及两种路径的选择说明见 自托管总览DataForSEO 凭据完整获取步骤docs/DATAFORSEO_API_KEY.md本主题的仓库版文档与本文互为印证docs/SELF_HOSTING_DOCKER.mdGoogle Search Console 集成配置docs/SELF_HOSTING_GOOGLE_SEARCH_CONSOLE.md。【免费下载链接】open-seoOpen source alternative to Semrush and Ahrefs项目地址: https://gitcode.com/GitHub_Trending/op/open-seo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考