部署与本地运行

GeekAI-Agent 支持两种运行方式：

  • Docker Compose 部署：一次启动 MySQL、Redis、API 和 Web，适合快速体验与服务器部署。
  • 本地运行：API 和 Web 在宿主机运行，便于断点调试和二次开发。

源码仓库：yangjian102621/geekai-agent

Docker Compose 部署

环境要求

准备一台安装了 Docker Engine 和 Docker Compose v2 的 Linux、macOS 或 Windows 主机。建议至少提供 2 核 CPU、4 GB 内存和 20 GB 可用磁盘。

先确认命令可用：

docker --version
docker compose version

1. 拉取源码

git clone https://github.com/yangjian102621/geekai-agent.git
cd geekai-agent/docker

后续所有 Compose 命令都在 geekai-agent/docker 目录执行。Compose 会使用当前目录里的配置、数据库初始化脚本和持久化目录。

2. 检查生产配置

本地体验可以直接使用仓库提供的默认配置。部署到公网前，至少修改以下两处：

  • conf/config.toml：MysqlDns、Redis.Password、Session.SecretKey 和 AdminSession.SecretKey。
  • docker-compose.yaml：MYSQL_ROOT_PASSWORD 和 Redis --requirepass 参数。

MySQL、Redis 两边的密码必须与 conf/config.toml 保持一致。会话密钥应分别生成独立的高强度随机字符串，不要继续使用仓库中的开发示例值。

Compose 默认将 MySQL 的 3308 端口和 Redis 的 6381 端口映射到宿主机。生产环境不需要远程连接时，应删除对应的 ports 配置或通过防火墙禁止公网访问。

对公网提供服务时，只开放 Web 入口，并在其前面配置 Nginx、Caddy 等反向代理和 HTTPS；不要直接暴露 MySQL、Redis 和 API 管理端口。

3. 启动服务

docker compose up -d

首次启动会拉取所需镜像，并启动以下服务：

服务作用默认入口
geek-agent-web用户端与管理后台http://localhost:8081
geek-agent-apiGo APIhttp://localhost:6789
geek-agent-mysqlMySQL 8宿主机端口 3308
geek-agent-redisRedis 6宿主机端口 6381

查看启动状态：

docker compose ps
docker compose logs --tail=200 geek-agent-api

容器显示 running 只代表进程已启动，还需要确认 MySQL 完成初始化且 API 没有连接错误：

docker compose logs --tail=200 geek-agent-mysql
docker compose logs --tail=200 geek-agent-api
curl -I http://localhost:8081

MySQL 日志不再出现初始化错误、API 日志显示监听地址，且 curl 返回 HTTP 响应后，再访问：

  • 用户端：http://服务器IP:8081
  • 管理后台：http://服务器IP:8081/#/admin

Compose 将 docker/data/mysql/init.d/ 挂载到容器的 /docker-entrypoint-initdb.d/。其中的 geekai_agent_sanitized.sql 是容器首次启动使用的初始化文件；项目根目录 database/ 下的同名文件供手动初始化本地数据库使用，两份文件应保持一致。

初始化 SQL 会创建本地体验账号和管理员账号。根据本仓库的安全规范，文档不重复记录公开默认密码；请在初始化 SQL 的“Public bootstrap”注释中确认临时账号，并在首次登录后立即修改密码。

初始化脚本只执行一次

MySQL 官方镜像仅在数据目录为空时执行 data/mysql/init.d/ 中的 SQL。修改初始化脚本后，已有数据库不会自动重新导入。不要为了重新初始化而直接删除生产数据目录。

4. 常用运维命令

# 查看全部容器
docker compose ps

# 查看 API 日志
docker compose logs -f geek-agent-api

# 查看 MySQL 日志
docker compose logs -f geek-agent-mysql

# 重启服务
docker compose restart

# 停止并移除容器，保留绑定目录中的数据
docker compose down

# 拉取新镜像并重新启动
docker compose pull
docker compose up -d

不要随意执行 docker compose down -v，也不要直接清理 docker/data/。升级或迁移前应先备份数据库、上传文件和配置。

本地运行

本地运行适合开发 GeekAI-Agent：MySQL 和 Redis 提供基础依赖，Go API 监听 5678 端口，Vite 开发服务器监听 8888 端口并代理 API 请求。以下 Shell 命令适用于 macOS、Linux 或 Windows WSL。

环境要求

  • Go 1.23
  • Node.js 20 LTS 和 npm
  • MySQL 8.0
  • Redis 6.0 及以上
  • Git

确认版本：

go version
node --version
npm --version
mysql --version
redis-cli --version

1. 拉取源码

如果尚未克隆项目：

git clone https://github.com/yangjian102621/geekai-agent.git
cd geekai-agent

2. 启动 MySQL 和 Redis

确保本机 MySQL、Redis 已启动，并能从以下地址连接：

  • MySQL：127.0.0.1:3306
  • Redis：127.0.0.1:6379

也可以复用 Docker Compose 中的 MySQL 和 Redis：

cd docker
docker compose up -d geek-agent-mysql geek-agent-redis
cd ..

复用 Compose 依赖时，API 应连接宿主机的 MySQL 3308 端口和 Redis 6381 端口，并使用 docker-compose.yaml 中配置的密码。

3. 初始化数据库

当前初始化文件会自动创建 geekai_agent 数据库、数据表和脱敏的本地体验数据：

mysql -uroot -p < database/geekai_agent_sanitized.sql

该脚本包含 DROP TABLE IF EXISTS。只应导入全新的开发数据库，不要在已有数据的生产库中重复执行。

4. 配置并启动 API

复制本地配置文件：

cd api
cp config.toml config.local

编辑 api/config.local，至少核对：

Listen = "0.0.0.0:5678"
MysqlDns = "root:你的数据库密码@tcp(127.0.0.1:3306)/geekai_agent?charset=utf8mb4&collation=utf8mb4_unicode_ci&parseTime=True&loc=Local"

[Redis]
  Host = "127.0.0.1"
  Port = 6379
  Password = ""
  DB = 0

如果使用 Compose 提供的依赖，将 MySQL 端口改为 3308、Redis 端口改为 6381，并填写与 Compose 一致的密码。

安装 Go 依赖并启动 API：

go mod download
CONFIG_FILE=config.local go run .

看到服务监听 0.0.0.0:5678 后，保持该终端运行。

5. 启动 Web

打开另一个终端，在项目根目录执行：

cd web
npm ci
npm run dev

访问 http://localhost:8888。开发环境会把 /api 和 /static 请求代理到 http://localhost:5678。

管理后台地址为 http://localhost:8888/#/admin。初始化账号说明位于数据库初始化 SQL 的“Public bootstrap”注释中，首次登录后应立即修改默认密码。

6. 验证本地环境

依次检查：

  1. http://localhost:8888 可以打开用户端。
  2. http://localhost:8888/#/admin 可以打开管理后台。
  3. API 终端没有 MySQL 或 Redis 连接错误。
  4. 登录后台后可以读取系统配置。
  5. 添加一个智能体应用并完成一次对话。真实对话还需要准备对应平台的 API Key、可用额度和访问该平台的网络环境。

停止本地服务时，在 API 和 Web 终端按 Ctrl+C。如果基础依赖由 Compose 启动：

cd docker
docker compose stop geek-agent-mysql geek-agent-redis

首次启动后的配置

部署完成后建议按以下顺序配置：

  1. 修改初始化账号密码。
  2. 在“系统设置”中配置站点名称和本地或对象存储。
  3. 添加一个 OpenAI 兼容接口，或导入 Coze、Dify、阿里云百炼智能体。
  4. 设置默认聊天应用。
  5. 完成一次登录、对话和积分扣减验证。
  6. 最后再按需启用短信、邮件和支付渠道。

相关教程：智能体配置 · Coze 配置 · Dify 配置 · 阿里云百炼配置