5.2 KiB

Raw Permalink Blame History

gitlink-ci 参考手册

本文档定义 CI/CD 的 API 字段映射、错误诊断模式、流水线配置参考和已知问题。

一、前置条件：DevOps 状态

检查方法

gitlink-cli repo +info --owner <owner> --repo <repo> --format json
# 关注字段: "open_devops": true/false

open_devops	CI 命令可用性
`true`	`ci +builds/logs/restart/stop` 全部可用
`false`	所有 CI 命令返回 `[-1] 接口数据异常`

激活 DevOps

# 通过 Raw API 激活
gitlink-cli api POST /<owner>/<repo>/activate

# 或通过 Web 页面：
# 仓库 → 设置 → DevOps → 开启

实测数据

在 chroe/gitlink-cli 上（open_devops: false）：

gitlink-cli ci +builds --owner chroe --repo gitlink-cli
# 输出: 错误: 获取构建列表失败: [-1] 接口数据异常

二、CI API 字段映射

ci +builds 预期响应结构

{
  "ok": true,
  "data": {
    "builds": [
      {
        "id": 42,
        "number": 42,
        "status": "failed",
        "branch": "feature/new-auth",
        "commit": "abc1234def",
        "commit_message": "feat: add new auth",
        "created_at": "2026-06-12T10:00:00+08:00",
        "duration": 120,
        "stages": [
          { "number": 1, "name": "build", "status": "success" },
          { "number": 2, "name": "test", "status": "failed" }
        ]
      }
    ],
    "total_count": 50
  }
}

字段	用途
`number`	构建编号，用于 `ci +logs` / `ci +restart` / `ci +stop`
`status`	`success` / `failed` / `running` / `stopped`
`branch`	触发构建的分支
`commit`	触发构建的 commit SHA
`stages`	流水线阶段列表，每个 stage 有独立状态
`duration`	构建耗时（秒）

ci +logs API

GET /<owner>/<repo>/builds/<build-number>/logs/<stage>/<step>

参数说明：

build-number：从 ci +builds 获取
stage：阶段编号，默认 1（编译阶段）
step：步骤编号，默认 1

三、构建错误诊断模式库

编译错误

模式	正则	常见原因
依赖缺失	`cannot find package`	`go.mod` 或 `package.json` 不完整
语法错误	`syntax error`	代码语法问题
类型错误	`cannot use .* as type`	类型不匹配
未定义引用	`undefined:`	缺少 import 或拼写错误
导入路径错误	`no required module provides package`	Go module 路径变更

测试失败

模式	常见原因
`FAIL: TestXxx`	测试断言失败
`panic: runtime error`	测试中空指针或越界
`--- FAIL: TestXxx (0.00s)`	测试立即失败（setup 错误）
`too many arguments`	测试函数签名不匹配

环境/基础设施

模式	常见原因
`connection refused`	数据库/外部服务不可用
`out of memory`	构建内存不足
`permission denied`	密钥或文件权限问题
`docker: not found`	构建环境缺少 Docker
`No space left on device`	磁盘空间不足

GitLink 特定错误

模式	说明
`[-1] 接口数据异常`	仓库未开启 DevOps
返回 HTML 而非 JSON	API 路径错误（如缺少 `/v1/` 前缀）

四、流水线配置文件

文件位置

仓库根目录/
└── .devops/
    └── <流水线名称>.yml

示例配置（Go 项目）

name: 构建部署
on:
  push:
    branches: [master]
jobs:
  build:
    runs-on: docker
    steps:
      - name: 构建
        run: go build -o app .
      - name: 测试
        run: go test ./...
      - name: 部署
        run: |
          ssh root@server "cd /opt/app && git pull && docker build -t app . && docker-compose up -d"

关键注意事项

Docker 构建需配置 GOPROXY=https://goproxy.cn,direct（国内网络）
服务器 Docker daemon 需配置国内镜像加速器（/etc/docker/daemon.json）
GitLink 密钥管理：敏感信息通过 deploy_server.server_password 注入
使用 git fetch + git reset --hard 替代 git pull 避免本地修改冲突

五、已知限制

限制	说明
DevOps 默认关闭	大部分仓库的 `open_devops` 为 `false`，需手动开启
接口数据异常	通用错误码 `-1`，无结构化错误信息
无构建触发 API	无法通过 CLI 触发新构建，只能通过 git push 触发
日志可能截断	长日志可能被分页或截断

六、常见问题

Q: 所有 CI 命令都返回"接口数据异常"？

A: 99% 的情况是因为仓库未开启 DevOps。检查 repo +info 中的 open_devops 字段。

Q: 如何触发一次新构建？

A: GitLink 没有"手动触发构建"的 API。只能通过 git push 到触发分支（如 master）来启动构建。

Q: ci +logs 的 stage/step 是什么意思？

A: 每个流水线有多个 stage（阶段），每个 stage 有多个 step（步骤）。默认 stage=1, step=1 通常是第一个编译步骤。

Q: CI 构建没有日志输出？

A: 尝试不同的 stage/step 组合。如果 stage=1,step=1 无输出，试试 stage=2,step=1。

5.2 KiB Raw Permalink Blame History Unescape Escape