云端私有化部署说明

配置要求

---

场景	CPU	内存	磁盘	适用情况
最低可运行	1 核	512MB-1GB	5GB	个人低并发
推荐生产	2 核	2GB	20GB-50GB	小团队、日常生产使用
较高配置	4 核	4GB-8GB	100GB+	用户较多、上传文件较多、访问量较高

部署方式

点击查看docker部署说明点击收起docker部署说明

docker部署

Step 1：创建数据映射目录

cd opt/heguzai-api   //项目文件夹
mkdir -p data uploads credentials  //创建数据目录
data //数据库目录
uploads //头像文件目录
credentials //初始密码文件目录

Step 2：编辑配置文件

cp .env.example .env
chmod 600 .env
nano .env

.env说明

按需填写，如果只需要ip,填写

• JWT_ACCESS_SECRET=生成一个随机字符串替换此处
• JWT_REFRESH_SECRET=生成另一个随机字符串替换此处
• JWT密钥你可以使用Secret Key Generator网站 点击进入 在线生成 或者 JWT Secrets网站 点击进入

如果你安装了Openssl 可以使用下方的命令生成JWT密钥

openssl rand -base64 64

如果你安装了nodejs，你可以使用下方的命令生成JWT密钥

node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

# HeguZai API 服务端配置
# 复制此文件为 .env 并根据实际情况修改

# ===========================================
# 基础服务配置
# ===========================================
# 服务端口
PORT=5089

# 数据库路径（相对路径或绝对路径）
DATABASE_PATH=./data/heguzai.db

# 调试模式（true/false）
DEBUG=false

# ===========================================
# JWT Token 配置
# ===========================================
JWT_ACCESS_SECRET=生成一个随机字符串替换此处 
JWT_REFRESH_SECRET=生成另一个随机字符串替换此处
JWT_ACCESS_EXPIRY_MINUTES=60
JWT_REFRESH_EXPIRY_DAYS=7

# ===========================================
# OAuth 第三方登录配置
# ===========================================
# 微信开放平台配置（可选）
WECHAT_APP_ID=
WECHAT_APP_SECRET=
WECHAT_REDIRECT_URI=https://yourdomain.com/api/oauth/wechat/callback

# QQ 互联配置（可选）
QQ_APP_ID=
QQ_APP_KEY=
QQ_REDIRECT_URI=https://yourdomain.com/api/oauth/qq/callback

# Web 端回调地址
OAUTH_WEB_CALLBACK_URL=https://yourdomain.com/api/oauth/web/callback

# 桌面客户端回调地址
OAUTH_DESKTOP_CALLBACK_URL=http://127.0.0.1:[port_number]/oauth/desktop/callback

# ===========================================
# CORS 跨域配置
# ===========================================
CORS_ALLOW_ORIGIN=*

# ===========================================
# SMTP 邮件发送配置（可选），用于密码找回
# ===========================================
SMTP_HOST=smtp.qq.com
SMTP_PORT=587
SMTP_USERNAME=your_email@qq.com
SMTP_PASSWORD=你的邮箱授权码
SMTP_FROM_EMAIL=heguzai@yourdomain.com
SMTP_FROM_NAME=合谷仔 AI
SMTP_USE_TLS=true

# ===========================================
# 其他配置
# ===========================================
UPLOAD_DIR=./uploads
CREDENTIALS_DIR=./credentials
PUBLIC_BASE_URL=https://yourdomain.com //公网地址

Step 3：启动服务

docker run -d \
  --name heguzai-api \
  --restart unless-stopped \
  --env-file .env \
  -p 5089:5089 \
  -v "$PWD/data:/app/data" \
  -v "$PWD/uploads:/app/uploads" \
  -v "$PWD/credentials:/app/credentials" \
  ghcr.io/chaomiss/heguzai-api:latest

查看日志：

docker logs -f --tail=100 heguzai-api

验证服务：

curl -fsS http://127.0.0.1:5089/health

返回结果： 正常会返回包含 success: true、status: ok、serverName: heguzai-api-go 的 JSON。

chao@TNAS:~/docker/heguzai-api# curl -fsS http://127.0.0.1:5089/health
{"features":{"ai":false,"auth":true,"deepThinking":false,"formula":false,"knowledge":true,"sync":true,"upgradedPlanning":false,"vba":false},"message":"heguzai-api-go","serverName":"heguzai-api-go","serverType":"full","status":"ok","success":true,"version":"2.0.0"}chao@TNAS:~/docker/heguzai-api#

Docker Compose 部署

如果希望用 Compose 管理容器，可以创建 docker-compose.yml：

• 新手提示： 在你的项目文件夹根目录新建docker-compose.yml，复制一下内容到文件中保存即可

services:
  heguzai-api:
    image: ghcr.io/chaomiss/heguzai-api:latest
    container_name: heguzai-api
    restart: unless-stopped
    ports:
      - "5089:5089"
    env_file:
      - .env
    volumes:
      - ./data:/app/data
      - ./uploads:/app/uploads
      - ./credentials:/app/credentials

启动服务：

docker compose  up -d

点击查看 源码构建部署说明点击收起 源码构建部署说明

源码构建部署

如果需要从源码构建镜像：

cd opt/
git clone https://gitee.com/heguzai/heguzai-api.git
cd /heguzai-api

cp .env.example .env
nano .env
docker compose up -d --build

点击查看 传统 Go 部署说明点击收起 传统 Go 部署说明

传统 Go 部署说明

如果需要传统 Go 部署：

go mod download
CGO_ENABLED=1 go build -ldflags="-s -w" -o heguzai-api-go .
set -a
. ./.env
set +a
./heguzai-api-go

SQLite 驱动依赖 CGO，服务器需要安装 gcc 和基础构建工具。

默认管理员

首次启动会自动创建默认管理员：

邮箱：admin@system.local
密码：admin123

首次登录后请立即修改密码。默认管理员凭据会写入 credentials/ 目录，请妥善保管，并确保该目录不会被公网访问。

数据持久化

以下目录需要持久化并定期备份：

目录	用途
data/	SQLite 数据库
uploads/	用户上传文件
credentials/	首次管理员凭据

升级镜像或重建容器时，不要删除这些目录。

常用docker命令

先进入有 docker-compose.yml 的部署目录，例如 Linux：

cd /opt/heguzai

常用命令如下。

检查配置：

docker compose config --quiet

构建并启动：

docker compose up -d --build heguzai-api

只启动：

docker compose up -d heguzai-api

查看运行状态：

docker compose ps

查看日志：

docker compose logs -f heguzai-api

查看最近 100 行日志：

docker compose logs --tail=100 heguzai-api

重启服务：

docker compose restart heguzai-api

停止服务：

docker compose stop heguzai-api

停止并删除容器，不删数据库卷：

docker compose down

进入容器内部：

docker exec -it heguzai-api sh

查看健康状态：

curl http://127.0.0.1:5089/health