GEO 系统部署报错排查手册：nginx+systemd 与 Docker Compose 双方案怎么选_GEO系统运维,GEO二次开发,部署运维 ai时代获客

一句话导语：GEO 系统源码入手后怎么部署、报错怎么查、升级备份怎么做，本文一份说透。

引言钩子：源码到手，部署是第一道坎

GEO 系统部署说难不难，说不难也难：源码目录里同时躺着 Go/Gin 后端、异步 Worker、Vue 三端前端和一套 Playwright 爬虫，任何一环没对齐，nginx 就给你返回 502，或者收录查询整批失败。本篇文章不是架构科普，而是一份可以直接照做的 GEO 系统运维手册：先讲清 nginx+systemd 与 Docker Compose 两套方案各自适合谁，再给出一张”现象 → 原因 → 解法”的排查对照表，最后把备份与升级做成能复制执行的脚本。
需要部署协助或长期运维支持，可以联系张先生（电话/微信：13632957375）。

为什么值得为部署花这篇工夫？Gartner 预测 2026 年传统搜索量将下降 25%，而国内 AI 搜索入口已经分流到百度插件助手 2.94 亿用户这一量级；GEO（Generative Engine Optimization，AI 生成式引擎优化）要抢的正是”被 AI 推荐”的增量流量，系统跑不起来，前面所有关键词与内容动作全部归零。本文的承诺是：读完你就能独立完成一次 GEO 系统源码部署，并把日常部署报错的定位时间压缩到半小时以内。

机制原理：先看懂进程分工，报错才能自动归位

GEO 系统的部署形态由进程分工决定：一个 nginx 入口、一个 Go API 进程、一个异步 Worker，外加后台 MySQL 8 与 Redis 7，以及一套 Node/Playwright 爬虫。 想明白”哪个进程负责哪件事”，部署报错就能按归属自动定位：nginx 报错先查反代与静态目录，API 报错查数据库连接，队列不消费查 Worker 与 Redis，收录失败查爬虫宿主环境与账号池。

后端是 Go 1.25 + Gin + GORM + MySQL 8 + Redis 7，前端是 Vue 3 的三端应用。所有流量都收敛到 nginx 这一个入口，再按路径分流到五组入口：/adminapi（总后台）、/agentapi（服务商）、/enterpriseapi（企业）、/verify（验证分享）、/workerapi（回调）。部署第一步永远是配好 nginx 反代而不是直接暴露后端端口，因为多租户隔离、登录限流、bcrypt 密码校验都发生在这道门以内。

为什么要专门设一个异步 Worker？因为 AI 生成、建站、收录查询、推文这类任务动辄几秒到几分钟，同步处理会把接口拖死。它们的实现方式是消费 Redis 队列：失败采用指数退避重试，反复失败进入死信队列，从而避免爬虫或模型网关瞬时抖动时对上游发起重试风暴。看懂这一条，你就能解释为什么”Worker 没启动时，所有建站与收录任务都静止不动”——这不是 bug，是架构。

sitegen 智能建站把每个站点渲染成独立 SQLite + 全静态 HTML，由 nginx 直出、首屏秒开，所以建站模块对应用服务器几乎零压力，压力全集中在生成那一刻的 Worker 与模型网关（OpenAI 兼容接口、默认流式 SSE）上。生产环境因此默认采用宿主机 nginx + systemd（api/worker/web） 的组合：systemd 负责开机自启与崩溃拉起，Docker Compose 只是备选，适合快速体验与环境隔离，代价是爬虫对宿主依赖更敏感。这一权衡在后面的选型章节展开。

GEO 平台 = 企业 AI 搜索优化的「获客中台」+ 服务商 AI 搜索优化的「分销经营平台」。

现状诊断：部署报错自测清单，先对号入座再动手

绝大多数 GEO 源码部署报错都可以归入五类：进程没起来、nginx 反代写错、MySQL/Redis 连不上、Worker 不消费队列、爬虫宿主环境缺依赖。 在翻开日志之前，先用下表给自己的报错贴标签，能省下一大半排障时间。

贴完标签，再做 5 项快速体检，每一项都有明确判断标准：

• 端口：ss -ltnp 确认 80/443、8080（api）、3306（MySQL）、6379（Redis）都在监听；
• 进程：systemctl status geo-api geo-worker 或 docker compose ps 确认都处于运行态；
• 日志：api 与 worker 的 journal/容器输出里有没有 FATAL、panic 或 connect refused；
• 连通：redis-cli ping 拿到 PONG，mysql 客户端能登录，密码以 .env 为准；
• 磁盘：df -h 确认根分区与站点目录没写满——SQLite 写不进会表现为”建站失败”而不是”磁盘满”。

做完贴标签加体检，再看下一节的分步排查，你会发现已经定位了 80% 的问题。这一步的真正价值在于：部署报错最怕的是”不知道从哪查起”，清单把排查范围从整个系统收敛到一两个进程。

方法框架：GEO 源码部署报错分步排查手册

排查顺序固定为：进程 → 网络与反代 → 数据层 → 队列与 Worker → 爬虫 → 防火墙，每一步都有可判定的退出标准。 按这个顺序走，GEO 源码部署的绝大多数报错能在半小时内找到根因；跳步乱查（比如一上来就怀疑代码）才是排障效率低的头号原因。

1. 进程存活：systemctl status geo-api geo-worker（或 docker compose ps），failed/exited 的先拉起再看报错；
2. 反代连通：curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:8080/adminapi/...，非 2xx 即 nginx 到 api 这一段有问题；
3. 数据层：redis-cli ping 拿 PONG，mysql -h 127.0.0.1 -u geo -p 能登录，账号以 .env 为准；
4. 队列：redis-cli LLEN geo:queue:* 看积压长度，积压只增不减 ≈ Worker 消费卡死，指数退避中的任务会反复延迟入队；
5. 爬虫宿主：node -e "require('playwright')" 能加载且能拉起 Chromium，缺系统库时会静默失败；
6. 防火墙：firewall-cmd --list-all 确认只放行必要端口，firewalld 默认 DROP，MySQL 保持 127.0.0.1 本机绑定即可；
7. 收尾复现：重启问题进程，观察 5 分钟日志无新报错，再跑一遍”登录 → 建站 → 写文 → 收录查询”的端到端。

两个高频场景值得单独讲。502 场景：先 curl 127.0.0.1:8080 直接打 api，能通说明问题只在 nginx 一层（路径、proxy_pass、upstream 名称），不通则问题在进程或数据层；nginx 错误日志 /var/log/nginx/error.log 里会写明是 connect 失败还是超时。收录查询整批失败场景：先确认 Worker 在消费”收录查询”队列，再看爬虫进程是否存活——它依赖真实浏览器与登录态，比 api 更受宿主环境影响，容器内外表现差异极大。

落地工具：可直接复制的 Compose、systemd 与备份脚本

这一节给出三件可直接复制的资产：docker-compose.yml、两份 systemd 单元文件、一份每日备份脚本，全部按 GEO 系统真实技术栈（Go 1.25/Gin/GORM、MySQL 8、Redis 7）编写，改路径与密钥即可上线。

# docker-compose.yml —— GEO 系统 Docker Compose 部署示例
services:
  mysql:
    image: mysql:8
    environment:
      MYSQL_DATABASE: geo
      MYSQL_USER: geo
      MYSQL_PASSWORD: "改成强口令"
      MYSQL_ROOT_PASSWORD: "改成强口令"
    volumes: [mysql-data:/var/lib/mysql]
    healthcheck:
      test: ["CMD-SHELL", "mysqladmin ping -h 127.0.0.1 -ugeo -p$$MYSQL_PASSWORD"]
      interval: 10s
      retries: 5

  redis:
    image: redis:7
    command: redis-server --appendonly yes   # 队列与缓存，建议开 AOF
    volumes: [redis-data:/data]

  api:
    build: ./apps/server                     # Go 1.25 多阶段构建
    depends_on: [mysql, redis]
    environment:
      DB_DSN: "geo:改成强口令@tcp(mysql:3306)/geo"
      REDIS_ADDR: "redis:6379"
    ports: ["8080:8080"]                     # 正式环境建议去掉映射，只由宿主 nginx 反代

  worker:
    build: ./apps/server
    command: ["./worker"]                    # 同一镜像，入口指向异步 Worker
    depends_on: [mysql, redis]

  web:
    image: nginx:1.27
    volumes:
      - ./apps/web/dist:/usr/share/nginx/html:ro
      - ./deploy/nginx.conf:/etc/nginx/conf.d/default.conf:ro
    ports: ["80:80"]

volumes:
  mysql-data:
  redis-data:

注意上面的示例里爬虫没有进 Compose，这是有意为之。爬虫是 Node + Playwright（Chromium）并发池，容器里跑 Chromium 需要额外补系统库并处理 –no-sandbox，内存上限一低就 OOM，这一兼容注意在差异化分支展开。

# ===== 文件 1：/etc/systemd/system/geo-api.service（Go/Gin API）=====
[Unit]
Description=GEO API (Go/Gin)
After=network.target mysqld.service redis.service
Wants=network.target

[Service]
Type=simple
User=geo
Group=geo
WorkingDirectory=/opt/geo/apps/server
EnvironmentFile=/opt/geo/apps/server/.env
ExecStart=/opt/geo/bin/geo-api
Restart=on-failure
RestartSec=5
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target

# ===== 文件 2：/etc/systemd/system/geo-worker.service（Redis 队列消费者）=====
[Unit]
Description=GEO Worker (Redis queue consumer)
After=network.target mysqld.service redis.service geo-api.service

[Service]
Type=simple
User=geo
Group=geo
WorkingDirectory=/opt/geo/apps/server
EnvironmentFile=/opt/geo/apps/server/.env
ExecStart=/opt/geo/bin/geo-worker
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

说明：web（前端）不需要独立守护进程——apps/web 构建产物由宿主机 nginx 直接托管，nginx 本身由发行版 systemd 管理；五个 API 路径反代到 127.0.0.1:8080，sitegen 站点目录单独配 root。systemd 方案记住一条：改完单元文件必须 systemctl daemon-reload，否则改的配置不生效，这是新手最容易踩的空转坑。

从关键词引擎的提问词库到 AI 官网的自动生成，再到内容生产与媒体分发，一套完整的 GEO 平台让企业无需自建技术团队就能跑通全链路，也让服务商能以极低的边际成本服务多家客户。

#!/usr/bin/env bash
# GEO 系统每日备份：MySQL + Redis + sitegen SQLite + .env，保留 7 天
set -euo pipefail
STAMP=$(date +%F)
BK=/data/geo-backup/$STAMP
mkdir -p "$BK"
source /opt/geo/apps/server/.env        # 引入 DB_PW、REDIS_PW 等变量（按实际 .env 调整）

mysqldump -h 127.0.0.1 -ugeo "-p${DB_PW}" geo > "$BK/geo.sql"
redis-cli -a "$REDIS_PW" BGSAVE || true
sleep 2
cp /var/lib/redis/dump.rdb "$BK/redis.rdb" 2>/dev/null || echo "warn: 无 Redis RDB"
tar czf "$BK/sites.tgz" /opt/geo/sites   # sitegen 每站独立 SQLite
cp /opt/geo/apps/server/.env "$BK/env.bak"
find /data/geo-backup -maxdepth 1 -type d -mtime +7 -exec rm -rf {} +

备份顺序有讲究：先停 Worker 排空队列，再 dump MySQL，最后拷贝 SQLite。 因为建站与收录是异步任务，如果在 Worker 运行中直接备份，可能备份到”任务已出队、但数据库还没落盘”的中间态；迁移到新机后，旧队列任务按新代码消费，还可能产生版本不一致。升级当天按”备份 → 停 Worker → 部署新代码 → 跑迁移 → 起服务 → 观察队列消费”执行，这个顺序比任何单独步骤都重要。

差异化分支：双方案怎么选，升级与二开怎么管

方案选择依据是规模与目的：单机小规模正式运营用 nginx+systemd，快速体验与多机隔离用 Docker Compose；业务量上来后，Worker 与爬虫要从 api 所在主机拆出去单独扩容。 没有”哪个更好”，只有”哪个更适合你当前的阶段”。

Docker 方案最需要警惕的是爬虫。收录查询依赖 Playwright 并发池真实驱动 AI 大模型平台提问，容器里跑 Chromium 是”能起但不好养”：要么在镜像里装齐系统库并关沙箱，要么把爬虫留在宿主机、只容器化 api/worker/web。实测中爬虫容器最常见的死法是内存不足被杀——收录查询是批量任务，并发池一开大，内存上限设置不当就 OOM。单机方案也有同样的边界：当企业租户多、并发任务密集时，单机同时跑 api、Worker、爬虫，CPU 与内存会被占满，此时应把 Worker 与爬虫迁到独立节点，api 与数据库留守。

升级与二开是长期运维的两条主线。升级按固定顺序执行：

1. 跑备份脚本，确认备份文件完整、可解压、可恢复；
2. 停 Worker（systemctl stop geo-worker），让 Redis 队列排空；
3. 拉取新代码、编译新二进制或打新镜像，执行数据库迁移命令；
4. 先起 api 验证五个入口健康，再起 worker，观察队列开始正常消费；
5. 保留上一版二进制与上一份备份，异常时 5 分钟内切回。

GEO 系统二次开发记住四点：一是改动只动 apps/server 与 apps/web 源码，配置走 .env，不直接改容器内文件；二是模型供应商 key 与提示词在总后台配置，不要写死在代码里——这决定了升级时 key 不用重录；三是五组入口路径不要改，改了 nginx 反代、前端路由、权限中间件三处都要同步；四是登录限流、多租户隔离（跨租户返回 403）是安全基线，二开不要绕过，一次越权事故的代价远高于省下的开发量。

MySQL 仅本机绑定、firewalld 默认 DROP 仅放行必要端口——部署安全基线不是建议，是默认。

预期管理：部署时间线、运维成本与翻车点

一次规范的 GEO 系统生产部署需要半天到一天，之后每月维护约 2-4 小时，真正的大头不是服务器租金，而是”排障时薪”。 这套系统由 6 类组件协作（nginx、api、worker、MySQL、Redis、爬虫），第一次部署时把每个环节验证到位，之后就是稳定器；验证不到位，后面每次升级都在还债。

时间线不长，为什么还有人翻车？因为翻车点集中在三个”搬运时刻”：升级前没备份、迁移时队列任务丢失、容器与宿主组件版本不一致。 比如迁移新机器时把旧 Redis 的 RDB 直接拷过去、队列里还有上百个建站任务，新 Worker 按新代码消费旧任务，轻则反复重试、重则死信堆积——这就是”备份了 MySQL 却丢了队列”的典型事故。判断标准是：备份验证 = 至少在一台临时机器上恢复过一次，而不是备份文件存在就行。另外，默认账号 admin/admin123 仅在开发期使用，生产部署后第一件事就是改密，这与 MySQL 仅本机绑定一样属于上线必做项。

再诚实一点：本文的方法在大并发场景下不适用。当你有几十上百个企业租户、每天数千次收录查询时，单机 nginx+systemd 组合会先到瓶颈——api 的 CPU、Redis 的内存、爬虫并发池的宿主资源互相争抢，此时该做的是把 Worker 与爬虫拆独立节点、加 Redis 集群、按队列拆分消费组，那是另一个量级的架构课题，不属于单机部署手册的射程。认清边界，比硬扛更专业。

所有耗时操作（AI 生成、爬虫查询、建站）全部异步化，前端不卡死——这是 GEO 系统的关键设计，也是你排查队列类问题时默认应该相信的架构前提。

如果你评估下来，发现”自己排障一小时 vs 交给专业运维”的成本账不划算——比如售后客户在等收录结果、服务商在冲交付量——把部署协助与运维服务交给有经验的人，把时间还给业务，是账面上更优的选择。专业运维的价值不在于”会执行命令”，而在于遇到 502、队列堆积、收录整批失败时按既定顺序快速定位，不拿你的生产环境试错。

FAQ：GEO 系统部署运维高频问题直答

1. GEO 系统部署报错怎么办？
先别改代码。按”进程 → 反代 → 数据层 → 队列 → 爬虫 → 防火墙”的顺序排查：systemctl status geo-api geo-worker 看进程，curl 127.0.0.1:8080/adminapi 测反代，redis-cli ping 与 mysql 登录验连通，再看队列积压与 worker 日志。八成报错集中在进程没起、nginx 路径写错、MySQL/Redis 连不上这三类，对照上文报错对照表即可定位。

2. GEO 系统 Docker 部署和 nginx+systemd 部署哪个好？
正式运营选 nginx+systemd，快速体验或环境隔离选 Docker Compose。systemd 方案与生产安全基线（MySQL 仅本机绑定、firewalld 默认 DROP）最贴合，爬虫直接吃宿主 Chromium 依赖；Docker 的坑主要在爬虫容器——要额外补系统库、处理 –no-sandbox，并发一高容易 OOM。

3. GEO 系统的 nginx 怎么配置？
nginx 是唯一入口：前端构建产物直接托管，/adminapi、/agentapi、/enterpriseapi、/verify、/workerapi 五个路径反代到 127.0.0.1:8080，sitegen 站点目录单独配 root。常见错误是 proxy_pass 路径与 location 前缀不一致导致 404，以及只开 80 不开 443 导致 https 跳转失败。

4. GEO 系统升级时 Redis 队列里的任务会丢吗？
会，这是最常见的升级事故。升级前必须停 Worker 并排空队列，把未消费任务处理完或另存，再切新代码；否则新 Worker 按新代码消费旧任务，轻则反复重试、重则进死信队列。备份 Redis 也不能只拷 RDB，要先确认队列已排空。

5. GEO 系统备份要备份哪些内容？
四类：MySQL 8 业务库、Redis 7（RDB/AOF）、sitegen 每站独立 SQLite、.env 与 nginx 等配置文件。顺序是先停 Worker 排空队列再 dump，SQLite 拷贝前确认无在建任务；备份后至少在一台临时机器恢复验证一次，才算一次有效备份。

购买系统后提供版本升级与运维支持：服务器环境、域名、备份、异常排查都可协助处理，需要深度定制的功能也支持二次开发对接，确保系统长期稳定运行。