跳到主要内容

常见问题

Docker 启动失败​

数据库迁移错误 no such table​

症状：容器日志显示 Failed to run database migrations: no such table: collaborator

原因：旧版本镜像迁移顺序问题（已修复）

解决：重新构建镜像

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

容器一直 Restarting​

排查步骤：

docker logs iforge-server --tail 50

常见原因：

  • 端口被占用 → 修改 .env 中的端口
  • 数据目录权限不足 → chmod -R 755 ./data

CORS 跨域错误​

症状：浏览器控制台 blocked by CORS policy

原因：后端 CORS 配置未生效

解决：

  1. 确认 docker-compose.yml 中 api 服务有 IFORGE_CORS_ORIGINS=*
  2. 确认 web 服务有 SERVER_API_URL=http://api:8081/api/v1
  3. 重新构建：docker compose build --no-cache api web

前端 API 请求打到 localhost​

症状：局域网访问时 API 请求发到 http://localhost:8081 而非实际 IP

原因：web Dockerfile 中 NEXT_PUBLIC_API_BASE 默认值未改为空

解决：确认 web Dockerfile 中 ARG NEXT_PUBLIC_API_BASE=（空值），重新构建 web 镜像。

Git push 返回 404​

症状：git push 返回 404 page not found

排查：

# 测试后端是否正常
curl http://localhost:8081/health

# 测试 Git HTTP 端点
curl http://localhost:8081/owner/repo.git/info/refs?service=git-upload-pack

常见原因：

  • 后端未启动或端口错误
  • 仓库不存在或无权限
  • 后端进程异常（重启后端）

SSH clone 失败​

症状：git clone ssh://git@host:2022/owner/repo.git 超时或拒绝连接

排查：

# 测试 SSH 端口
ssh -T git@host -p 2022

# 确认密钥已添加
ssh -v git@host -p 2022

常见原因：

  • SSH 端口未开放（防火墙/安全组）
  • SSH 密钥未在 iForge 中添加
  • IFORGE_SSH_ENABLED=false

WebSocket 连接失败​

症状：浏览器控制台 WebSocket connection failed: 404

原因：缺少 WebSocket upgrade 中间件（已修复）

解决：重新构建 server 镜像。

数据库切换​

当前版本支持 SQLite/MySQL/PostgreSQL 三种数据库。通过 Docker Compose profiles 切换：

# MySQL
IFORGE_DB_DRIVER=mysql
docker compose --profile mysql up -d

# PostgreSQL
IFORGE_DB_DRIVER=postgres
docker compose --profile postgres up -d

详见 Docker 部署 - 数据库选择。

信息

SQLite 对中小团队（< 100 人）完全够用，单文件备份简单，无需额外运维数据库。

CI/CD 相关问题​

Job 执行失败：Shell Executor is disabled​

症状：Pipeline Job 日志显示 ERROR: Shell Executor is disabled for security reasons.

原因：Job 未指定 image 字段，尝试使用 Shell Executor 在宿主机执行

解决：在 .iforge-ci.yml 中为 Job 添加 image 字段：

test:
  stage: test
  image: golang:1.21  # 必须指定镜像
  script:
    - go test ./...

Job 容器内存不足​

症状：Job 日志显示 OOMKilled 或容器被终止

原因：Job 容器内存超过 2GB 限制

解决：

  1. 优化构建脚本，减少内存占用
  2. 使用更小的基础镜像
  3. 分阶段构建，避免一次性加载大量数据

Job 无法访问网络​

症状：Job 中 curl、wget、git clone 等网络命令失败

原因：Job 容器默认禁用网络访问（--network=none）

解决：这是安全设计，Job 容器不应访问外部网络。如需下载依赖，请在构建镜像时预装，或使用制品缓存。