部署与初始化

淬炼AIGC实训平台采用 Docker 镜像私有化部署：后端 API 与前端 Web 拆分为两个镜像，配合外部的 MySQL 与 Redis 组成完整服务。本文介绍从零部署到完成初始化的全流程，适用版本 v1.3.7（截至 2026-10）。

环境要求

确认 Docker 可用：

docker --version
docker compose version

获取部署材料

淬炼为商业软件，部署前请通过微信 geekmaster01 获取以下材料：

1. Docker 镜像：API 与 Web 两个镜像（阿里云镜像仓库地址），版本与架构（amd64/arm64）与服务器匹配。
2. 许可信息：极客 AI 服务访问令牌（GeekServiceConfig.Token）与系统许可证书密钥（License）。
3. 数据库初始化脚本：geekai_edu.sql 全量建库脚本。

目录结构

推荐按以下结构组织部署目录：

geekai-edu/
├── docker-compose.yaml
├── conf/
│   ├── config.toml              # 后端配置
│   └── nginx/
│       ├── nginx.conf           # Nginx 主配置
│       └── conf.d/
│           └── geekai.conf      # 站点配置（含 /api 反向代理）
├── logs/                        # 后端日志（挂载到容器）
│   └── nginx/                   # Nginx 日志
├── static/                      # 上传文件与静态资源
├── data/                        # 运行数据
└── geekai_edu.sql               # 数据库初始化脚本（首次使用）

1. 初始化数据库

淬炼不内置 MySQL/Redis，请使用学校已有实例或自行部署（容器、云服务均可），要求 MySQL 8.0 与 Redis 6.0+。在 MySQL 实例上导入初始化脚本：

mysql -uroot -p -h 数据库地址 < geekai_edu.sql

脚本会自动创建 geekai_edu 数据库、全部数据表和本地体验数据。

2. 编写后端配置

创建 conf/config.toml，按实际环境修改以下必填项：

Listen = "0.0.0.0:5678"
MysqlDns = "geekai:你的数据库密码@tcp(数据库地址:3306)/geekai_edu?charset=utf8mb4&collation=utf8mb4_unicode_ci&parseTime=True&loc=Local"
StaticDir = "./static"
StaticUrl = "/static"
License = "你的系统许可证书密钥"

[GeekServiceConfig]
  BaseURL = ""              # 极客 AI 服务地址，按交付说明填写
  Token = "你的极客服务访问令牌"
  AppName = "淬炼"

[Session]
  SecretKey = "openssl rand -hex 32 生成"   # 用户会话密钥，高熵随机串
  MaxAge = 86400            # 会话有效期（秒），可按学校要求调大

[AdminSession]
  SecretKey = "另一把独立的随机密钥"          # 必须与 Session.SecretKey 不同
  MaxAge = 86400

[Redis]
  Host = "Redis地址"
  Port = 6379
  Password = "你的Redis密码"
  DB = 0

配置要点：

• 会话密钥：Session.SecretKey 与 AdminSession.SecretKey 必须是两把独立的高熵随机密钥（openssl rand -hex 32），禁止沿用示例值，否则服务会拒绝启动。
• 数据库连接：填写第 1 步准备的外部 MySQL/Redis 地址；容器内访问宿主机服务时使用宿主机内网 IP。
• 会话时长：Session.MaxAge 控制用户登录有效期，学校机房场景可按需调整为 7 天（604800）或 30 天（2592000）。
• 资源中继（可选）：部分校园网络拦截外网 CDN 导致 AI 生成图片/音视频转存失败时，可部署 relay 中继服务并配置 RelayURL、RelayToken。

3. 编写 Nginx 配置

Web 镜像为 Nginx 站点，conf/nginx/ 下的主配置与站点配置整体挂载进容器，站点配置需将 /api 与 /static 反向代理到 API 容器。

conf/nginx/nginx.conf（主配置）：

user  nginx;
worker_processes  auto;
error_log  /var/log/nginx/error.log notice;
pid        /var/run/nginx.pid;

events {
    worker_connections  1024;
}

http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;
    sendfile      on;
    keepalive_timeout  65;
    client_max_body_size 100m;

    include /etc/nginx/conf.d/*.conf;
}

conf/nginx/conf.d/geekai.conf（站点配置）：

server {
    listen 8080;
    server_name your-school.example.com;

    # 前端静态资源
    root /var/www/app/dist;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    # API 反向代理（SSE 流式响应需关闭缓冲）
    location /api/ {
        proxy_pass http://geekai-api:5678;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Connection "";
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 300s;
    }

    # 上传文件与静态资源
    location /static/ {
        proxy_pass http://geekai-api:5678;
        proxy_set_header Host $host;
    }
}

4. 编写 docker-compose.yaml

services:
  # 后端 API 程序
  geekai-api:
    image: registry.cn-shenzhen.aliyuncs.com/geekmaster/geekai-edu-api:v1.3.7-amd64
    container_name: geekai-edu-api
    restart: always
    ports:
      - "6710:5678"
    volumes:
      - /usr/share/zoneinfo/Asia/Shanghai:/etc/localtime
      - ./conf/config.toml:/var/www/app/config.toml
      - ./logs:/var/www/app/logs
      - ./static:/var/www/app/static
      - ./data:/var/www/app/data
    environment:
      - APP_DEBUG=false
      - LOG_LEVEL=info
      - CONFIG_FILE=config.toml

  # 前端应用
  geekai-web:
    image: registry.cn-shenzhen.aliyuncs.com/geekmaster/geekai-edu-web:v1.3.7-amd64
    container_name: geekai-edu-web
    restart: always
    ports:
      - "8080:8080"
    volumes:
      - ./logs/nginx:/var/log/nginx
      - ./conf/nginx/conf.d:/etc/nginx/conf.d
      - ./conf/nginx/nginx.conf:/etc/nginx/nginx.conf

说明：

• 镜像版本：v1.3.7-amd64 按实际交付版本与服务器架构调整，arm64 服务器使用 -arm64 后缀。
• 端口：Web 统一走 8080 入口；API 映射到宿主机 6710 仅供排障验证，公网环境应通过防火墙封禁，不要直接暴露。
• 目录挂载：logs/、static/、data/ 分别持久化日志、上传文件与运行数据，升级与备份都围绕它们进行。
• 时区：挂载宿主机 /etc/localtime 保证日志与统计时间正确。

5. 启动服务

docker compose up -d
docker compose ps
docker compose logs -f geekai-api

API 日志出现监听 0.0.0.0:5678 且无 MySQL/Redis 连接错误即启动成功。浏览器访问 http://服务器IP:8080：

6. 首次启动后的初始化

按以下顺序完成初始化：

1. 修改默认密码：使用交付材料中的初始管理员账号登录管理后台，立即修改密码。
2. 基础配置（系统设置 → 基础配置，/admin/config/basic）：站点标题、LOGO、备案号等。
3. 存储配置（系统设置 → 存储配置，/admin/config/storage）：选择本地或对象存储，详见存储配置教程。
4. 接入模型（API-KEY → 语言模型）：添加第一个 AI 渠道与对话模型，详见API-KEY 与语言模型教程。
5. 建立组织架构：创建院系、课程、行政班，导入学生，详见院系与课程班级教程。
6. 配置积分：为院系积分池充值并设置预警，详见校园积分管理教程。
7. 验证闭环：教师创建课程班与排课 → 管理员审核 → 学生登录完成一次创作。

升级

淬炼私有化部署暂不支持在线自动升级，升级步骤为：

1. 备份数据库与 static/、data/ 目录。
2. 修改 docker-compose.yaml 中的镜像版本号（保持配置与 Nginx 挂载不变）。
3. docker compose pull && docker compose up -d 重建容器。
4. 管理员登录后台，进入系统设置 → 数据库维护（/admin/config/migration）执行版本迁移；后台顶部出现迁移提醒时同样在此处理。

版本变更详见版本记录。

常见部署问题

API 启动即退出，提示「未授权」

config.toml 中 GeekServiceConfig.Token 为空或无效。按交付材料填写令牌后重启容器。

前端页面打开白屏或 404

检查 Nginx 站点配置的 root 是否指向 /var/www/app/dist，并确认 try_files $uri $uri/ /index.html; 已配置（前端为 history 路由）。

对话没有流式输出、长时间才一次性返回

Nginx 代理未关闭缓冲。确认 /api/ 的 proxy_buffering off; 配置生效。

生成的图片/音视频转存失败

服务器无法访问外部 CDN。可在能自由出网的服务器上部署 relay 中继服务，并在 config.toml 配置 RelayURL 与 RelayToken。

管理后台提示「数据库尚未完成迁移」

应用版本高于数据库结构版本。进入系统设置 → 数据库维护执行版本迁移后刷新页面。

忘记管理员密码

联系交付支持重置，或在 MySQL 中按交付文档的密码规则处理后端 admin_users 表。切勿直接删除表数据。