Docker 部署

Docker Compose 是 iForge 推荐的生产部署方式。

一键启动

# 1. 克隆仓库
git clone https://gitee.com/iforge-go/iforge.git
cd iforge

# 2. 复制环境变量配置（可选，不复制则使用默认值）
cp .env.example .env

# 3. 构建并启动（首次构建约 5-10 分钟）
docker compose up -d

# 4. 查看日志
docker compose logs -f

启动后访问 http://localhost:3000 注册首个管理员账户。

服务架构

┌─────────────────────────────────────────────────────────────┐
│                    Nginx 反向代理层                           │
│              (独立仓库 iforge-nginx 统一管理)                  │
│                                                              │
│  iforge-go.com ──────► iforge-site (文档站)                  │
│  www.iforge-go.com ──► iforge-site (文档站)                  │
│  demo.iforge-go.com ─┬─► iforge-web (前端)                  │
│                      └─► iforge-server (后端)                │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────┼─────────────────────────────────┐
│                        iForge 平台                             │
│                                                                │
│  ┌─────────────┐     ┌─────────────┐     ┌─────────────────┐ │
│  │  web:3001   │────▶│ server:8081 │────▶│   Database      │ │
│  │  (Next.js)  │     │   (Go)      │     │  SQLite/MySQL/  │ │
│  └─────────────┘     └──────┬──────┘     │  PostgreSQL     │ │
│                             │             └─────────────────┘ │
│                      ┌──────┴──────┐                          │
│                      │ server:2022 │                          │
│                      │ (SSH Git)   │                          │
│                      └─────────────┘                          │
│                             ▲                                 │
│                             │ claim job / report status       │
│                      ┌──────┴──────┐     ┌─────────────────┐ │
│                      │  runner     │────▶│  job 容器        │ │
│                      │ (iforge-    │ DooD│ (alpine 等)     │ │
│                      │  runner)    │     └─────────────────┘ │
│                      └─────────────┘                          │
└───────────────────────────────────────────────────────────────┘

端口映射

服务	容器内端口	宿主机端口	用途
server	8081	8080	HTTP API + Git HTTP
server	2022	22	SSH Git 协议
web	3001	3000	前端页面
mysql	3306	3306	MySQL 数据库（profile: mysql）
postgres	5432	5432	PostgreSQL 数据库（profile: postgres）
runner	—	—	无外部端口，通过 Docker socket 执行 job

数据持久化

数据卷挂载在 ./data 目录：

volumes:
  - ./data:/app/data

包含：

• iforge.db — SQLite 数据库
• logs/ — 运行日志
• repositories/ — Git 仓库裸存储

备份

直接打包 ./data 目录即可完成完整备份。

局域网访问

Docker 部署默认支持局域网访问，无需额外配置：

• 前端 API 地址按浏览器 hostname 动态适配
• 后端 CORS 设置为 *（反射任意 Origin）

从局域网其他机器访问 http://192.168.x.x:3000 即可，API 请求自动发到 http://192.168.x.x:8080。

自定义域名

部署在自有域名时，在 .env 中设置：

NEXT_PUBLIC_API_BASE=https://iforge.example.com/api/v1
IFORGE_CORS_ORIGINS=https://iforge.example.com

修改后重新构建：

docker compose build --no-cache web server
docker compose up -d

数据库选择

iForge 支持三种数据库，通过 Docker Compose profiles 切换：

SQLite（默认，适合开发）

docker compose up -d

MySQL（生产环境）

# 在 .env 中设置
IFORGE_DB_DRIVER=mysql
MYSQL_ROOT_PASSWORD=<strong-password>
MYSQL_PASSWORD=<strong-password>

docker compose --profile mysql up -d

PostgreSQL（生产环境）

# 在 .env 中设置
IFORGE_DB_DRIVER=postgres
POSTGRES_PASSWORD=<strong-password>

docker compose --profile postgres up -d

反向代理配置

生产环境建议使用 Nginx 作为反向代理。iForge 提供了独立的 iforge-nginx 仓库统一管理 Nginx 配置。

域名规划

域名	服务	说明
iforge-go.com	iforge-site	官方文档站
www.iforge-go.com	iforge-site	官方文档站
demo.iforge-go.com	iforge-web + iforge-server	演示平台

Nginx 配置示例

upstream iforge_web {
    server iforge-web:3001;
}

upstream iforge_server {
    server iforge-server:8081;
}

server {
    listen 443 ssl http2;
    server_name demo.iforge-go.com;

    ssl_certificate /etc/nginx/ssl/iforge-go.com.pem;
    ssl_certificate_key /etc/nginx/ssl/iforge-go.com.key;

    # 前端
    location / {
        proxy_pass http://iforge_web;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        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 X-Forwarded-Proto $scheme;
    }

    # API
    location /api/ {
        proxy_pass http://iforge_server;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        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 X-Forwarded-Proto $scheme;
        client_max_body_size 100M;
    }
}

详细说明请参考 iforge-nginx 仓库。

常用命令

docker compose up -d          # 启动
docker compose down           # 停止
docker compose restart        # 重启
docker compose logs -f server # 查看后端日志
docker compose logs -f web    # 查看前端日志
docker compose build --no-cache  # 重新构建（修改代码后）

CI/CD Runner 部署

iforge-runner 是独立项目，与 iforge 后端分开部署。采用 DooD 模式（Docker-out-of-Docker）：runner 本身运行在容器中，通过挂载宿主机 Docker socket 创建兄弟容器执行 job。

┌─────────────────────────────────────────────────────────┐
│  宿主机                                                  │
│                                                         │
│  ┌──────────────┐    docker.sock    ┌────────────────┐ │
│  │ iforge-runner│──────────────────▶│  Docker Daemon │ │
│  │  (容器)       │                   │  (宿主机)       │ │
│  └──────┬───────┘                   └───────┬────────┘ │
│         │ docker run                          │          │
│         └────────────────────────────────────▶│          │
│                                            ┌──▼────────┐ │
│                                            │ job 容器   │ │
│                                            │ (兄弟容器) │ │
│                                            └───────────┘ │
└─────────────────────────────────────────────────────────┘

前置条件

iforge 后端（server）已在同一宿主机上运行（默认端口 8080）。如果后端在其他机器上，需调整 IFORGE_RUNNER_SERVER 环境变量。

首次部署

Runner 需要先注册获取 token 才能启动，首次部署分两步：

第 1 步：注册 Runner（获取 token）

cd iforge-runner                    # 进入 runner 独立项目目录
cp .env.example .env

# 设置宿主机工作目录绝对路径（DooD 路径对齐必需）
# 替换为你的实际路径
echo 'IFORGE_RUNNER_HOST_WORKDIR=/home/admin/code/iforge-runner/data' >> .env

# 构建镜像并执行一次性注册命令
docker compose run --rm runner register \
  --server http://host.docker.internal:8081 \
  --name prod-runner \
  --admin <管理员用户名> \
  --password <管理员密码>

# 输出示例：
#   注册成功!
#     Runner Name: prod-runner
#     Token:       grt_xxxxxxxxxxxxxxxxxxxx

第 2 步：写入 token 并启动

# 将上一步返回的 token 写入 .env
echo 'IFORGE_RUNNER_TOKEN=grt_xxxxxxxxxxxxxxxxxxxx' >> .env

# 启动 runner
docker compose up -d

# 验证状态
docker compose logs -f
# 应看到：[runner] 启动,server=http://host.docker.internal:8081, workDir=/work, hostWorkDir=... (DooD 模式)

后续部署

token 已持久化在 .env 中，后续直接一键启动：

cd iforge-runner
docker compose up -d

更新 Runner

cd iforge-runner
git pull
docker compose build --no-cache
docker compose up -d

多 Runner 扩展

重复执行注册命令创建多个 runner，每个 runner 使用不同名称和 token。可通过 docker-compose.override.yml 定义多个 runner 服务实例实现水平扩展。

路径对齐

IFORGE_RUNNER_HOST_WORKDIR 是 DooD 模式的关键配置。runner 容器内 /work 通过 bind mount 映射到宿主机 ./data，但 runner 通过 docker CLI 创建 job 容器时，Docker daemon 需要宿主机绝对路径才能挂载。此环境变量将容器内路径转换为宿主机路径，确保 job 容器的 /workspace 不为空。

更新版本

git pull
docker compose build --no-cache server web
docker compose up -d

数据迁移

iForge 使用版本化 SQL 迁移，升级时自动执行。请确保 ./data 目录已备份。

安全配置

CI/CD 安全

Docker 部署时，CI/CD Job 容器默认施加以下安全限制：

# docker-compose.yml 中的 server 服务环境变量
environment:
  - IFORGE_CI_ENABLED=true
  - IFORGE_CI_ALLOW_SHELL_EXECUTOR=false  # 生产环境必须为 false
  - IFORGE_CI_KEEP_WORKDIR=false          # 自动清理工作目录

Job 容器运行时限制：

• --memory=2g：内存上限 2GB
• --memory-swap=2g：禁止使用 swap
• --cpus=2：CPU 上限 2 核
• --pids-limit=256：进程数上限
• --network=none：默认禁用网络访问

安全警告

切勿在生产环境设置 IFORGE_CI_ALLOW_SHELL_EXECUTOR=true，这会导致用户代码在宿主机直接执行，存在严重安全风险。