GEOFlow 详细部署教程

1. 项目简介

GEOFlow 是一个面向 GEO / SEO 内容运营场景的开源内容生产系统，它把模型配置、素材管理、任务调度、草稿审核和前台发布串成一条完整链路，适合搭建自动化内容站点或内部内容运营后台。

核心特性：

  • 多模型内容生成：兼容 OpenAI 风格接口，可接入不同 AI 服务商
  • 批量任务运行：任务创建、定时调度、队列执行、失败重试
  • 素材统一管理：标题库、关键词库、图片库、知识库、提示词集中管理
  • 审核与发布工作流：草稿、审核、发布三段式流程，可切换自动发布
  • 面向搜索展示优化：文章 SEO 元信息、Open Graph、结构化数据
  • PostgreSQL 运行时：默认基于 PostgreSQL，适合稳定运行和并发写入

系统架构：

层级 说明
Web / Admin 前台文章站点与后台管理页面
API / CLI /api/v1 提供机器接口，bin/geoflow 提供本地 CLI 能力
Scheduler / Worker 调度器负责扫描任务和入队，Worker 负责实际调用模型生成内容
Domain Services includes/ 中的任务、文章、队列、AI、检索等服务承载核心业务规则
Persistence PostgreSQL 作为运行时数据库

核心工作流程：
后台配置模型、提示词和素材库 → 创建任务并进入调度 → 调度器写入 job queue → Worker 调用 AI 生成正文 → 文章进入草稿、审核、发布链路 → 前台输出文章与 SEO 页面。

2. 部署前准备

2.1 硬件要求

根据官方部署文档，推荐的最低配置要求如下：

  • CPU：至少 2 核
  • 内存：至少 2GB
  • 硬盘空间：至少 20GB
  • 网络：稳定的互联网连接
  • 操作系统：一台可访问外网的 Linux 服务器

2.2 软件要求

使用 Docker 方式部署（推荐）：

  • Docker 24+
  • Docker Compose v2

使用本地 PHP 环境部署：

  • PHP 7.4+（推荐 8.0+）
  • PostgreSQL 14+

必需的 PHP 扩展：

  • pdo（数据库抽象层）
  • pdo_pgsql（PostgreSQL 数据库支持）
  • json（JSON 处理）
  • mbstring（多字节字符串处理）
  • session（会话管理）
  • curl（HTTP 请求，用于 AI API 调用）

3. 方式一：Docker Compose 部署（推荐）

这是官方推荐的部署方式，部署路径最短，默认包含 web + postgres + scheduler + worker，与仓库当前运行结构一致。

3.1 克隆项目仓库

1
2
git clone https://github.com/yaojingang/GEOFlow.git
cd GEOFlow

3.2 配置环境变量

复制环境变量文件：

1
cp .env.example .env

编辑 .env 文件，至少需要确认以下必填配置：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
# 站点访问地址
SITE_URL=https://your-domain.com

# 应用安全密钥（建议使用 32 位以上随机字符串）
APP_SECRET_KEY=replace-with-a-long-random-secret

# 数据库配置
DB_DRIVER=pgsql
DB_HOST=postgres
DB_PORT=5432
DB_NAME=geo_system
DB_USER=geo_user
DB_PASSWORD=change-this-password

# 服务端口
HOST_PORT=18080

# Cron 调度间隔（秒）
CRON_INTERVAL=60

# 时区
TZ=Asia/Shanghai

# 强制使用强密钥
REQUIRE_STRONG_APP_SECRET=true

3.3 启动服务

开发/演示环境：

1
2
docker compose build
docker compose up -d

生产环境（推荐）：

生产环境使用 docker-compose.prod.yml，基于 Nginx + php-fpm 而非 php artisan serve：

1
2
3
4
cp .env.example .env.prod
vi .env.prod

docker compose -f docker-compose.prod.yml --env-file .env.prod up -d --build

3.4 访问应用

部署完成后，通过以下地址访问：

  • 前台：http://localhost:18080 或 https://your-domain.com/
  • 后台：http://localhost:18080/geo_admin/ 或 https://your-domain.com/geo_admin/

3.5 数据持久化说明

默认情况下，Docker 部署会使用以下数据卷持久化数据：

  • PostgreSQL 数据：存储在 Docker 卷中
  • 上传文件：存储在 storage/app/public/uploads/ 目录

3.6 服务运行结构

Docker Compose 部署后，以下服务将同时运行：

服务 说明
web 提供前台和后台页面
postgres 提供运行时数据库
scheduler 负责任务扫描、入队、自动发布
worker 负责实际调用模型生成内容
init 首次运行时执行数据库迁移和初始化

4. 方式二：本地 PHP 环境部署

适合需要修改源码或深度定制的开发者。

4.1 环境准备

确保已安装 PHP 7.4+ 和 PostgreSQL 14+，并启用必要的 PHP 扩展。

验证 PHP 扩展：

1
php -m | grep -E "pdo|pgsql|json|mbstring|curl"

4.2 克隆项目

1
2
git clone https://github.com/yaojingang/GEOFlow.git
cd GEOFlow

4.3 配置数据库连接

设置环境变量：

1
2
3
4
5
6
export DB_DRIVER=pgsql
export DB_HOST=127.0.0.1
export DB_PORT=5432
export DB_NAME=geo_system
export DB_USER=geo_user
export DB_PASSWORD=geo_password

4.4 启动开发服务器

1
php -S localhost:8080 router.php

访问 http://localhost:8080/geo_admin/ 进入后台。

5. 初始配置

5.1 默认管理员账户

首次部署后，系统会创建默认管理员账户：

  • 用户名：admin
  • 密码：admin888

重要安全提醒：首次登录后必须立即修改管理员密码和 APP_SECRET_KEY。

5.2 首次登录检查清单

根据官方文档，首次登录后需要完成以下配置：

  1. 修改默认管理员密码
  2. 配置站点名称、描述、关键词和前台语言
  3. 配置至少一个可用的聊天模型
  4. 如需 RAG 检索，配置嵌入模型并设为默认
  5. 添加知识库、关键词、标题、作者和图片库
  6. 创建一个小型测试任务
  7. 验证首页、分类页、文章页和 Markdown 渲染

5.3 配置 AI 模型

进入后台后，访问 AI Configurator → AI Model Settings：

  • 填写 API URL、模型 ID、API Key 和模型类型
  • GEOFlow 支持 OpenAI 兼容的提供商和原生 Gemini 聊天/嵌入路由
  • 如需知识库 RAG 功能，还需要配置嵌入模型并将其设为默认嵌入模型

注意：如果知识库显示分块但向量数为零，通常是因为尚未配置可用的嵌入模型。

6. 安全注意事项

根据官方安全建议，部署时请注意以下事项：

  1. 立即修改默认密码：首次部署后立刻修改后台管理员密码
  2. 替换 APP_SECRET_KEY：生产环境必须替换为强随机密钥
  3. 保护环境变量文件：不要把 .env.prod 提交到仓库
  4. 限制数据库端口：不要默认对外暴露 PostgreSQL 端口
  5. 反向代理配置：生产环境使用 Nginx、Caddy 或云负载均衡器进行 HTTPS 终止

HTTPS 反向代理配置示例：

1
2
3
APP_URL=https://your-domain.com
TRUSTED_PROXIES=*
BOOST_BROWSER_LOGS_WATCHER=false

如果使用子目录部署（如 https://example.com/wiki），反向代理需要转发 X-Forwarded-Prefix: /wiki 头。

7. 更新与回滚

7.1 更新服务

1
2
git pull origin main
docker compose -f docker-compose.prod.yml --env-file .env.prod up -d --build

7.2 回滚操作

回退到目标 commit 或 tag，然后重新执行相同的构建命令：

1
2
git checkout <目标commit或tag>
docker compose -f docker-compose.prod.yml --env-file .env.prod up -d --build

8. 常见问题与解决方案

8.1 页面显示空白

可能原因：PHP 错误、数据库连接失败、文件权限问题。

解决方案：

  • 启用错误显示：php -d display_errors=1 -S localhost:8080 router.php
  • 检查错误日志
  • 检查数据库连接：php bin/db_maintenance.php check

8.2 无法启动服务器

可能原因：端口被占用、PHP 未安装、权限不足。

解决方案：

  • 检查端口占用：lsof -i :8080
  • 使用其他端口
  • 检查 PHP 安装：which php && php --version

8.3 数据库错误

可能原因：PostgreSQL 服务未运行、连接凭证错误、pdo_pgsql 扩展未安装。

解决方案：

  • 检查 PostgreSQL 服务状态：sudo systemctl status postgresql
  • 测试数据库连接：psql -h 127.0.0.1 -U geo_user -d geo_system -c "SELECT 1;"
  • 检查 pdo_pgsql 扩展：php -m | grep pgsql

8.4 无法登录后台

可能原因：用户名或密码错误、会话配置问题、数据库问题。

解决方案：

  • 生成新密码哈希并更新数据库中的管理员密码
  • 检查会话目录配置
  • 谨慎清理会话文件

8.5 AI 功能无法使用

可能原因：API Key 未配置、网络连接问题、API 配额耗尽。

解决方案：

  • 检查 AI 模型配置
  • 测试 API 连接
  • 查看错误日志

8.6 知识库显示分块但零向量

原因：尚未配置可用的嵌入模型。

解决方案：配置一个启用状态且类型为 embedding 的模型，提供有效的 API Key，确保提供商端点支持嵌入，并将该模型设为默认嵌入模型。配置完成后，重新保存或刷新知识库以使向量写入生效。

9. 部署架构总结

部署方式 适用场景 优势 访问地址
Docker Compose（开发） 快速体验、本地开发 部署简单，一键启动 http://localhost:18080
Docker Compose（生产） 生产环境 Nginx + php-fpm，稳定高效 https://your-domain.com/
本地 PHP 环境 开发者定制 完全可控，便于调试 http://localhost:8080

部署完成后，你可以通过 GEOFlow 构建完整的 GEO 内容运营系统，实现从素材管理、AI 内容生成到多站点分发的全流程自动化。建议先从小规模测试任务开始，验证内容质量和发布流程后再逐步扩大规模。