为 GitLab CI/CD 构建智能体

在 GitLab CI/CD 流水线中构建和运行 Flue 智能体。本指南涵盖在 CI 流水线中构建、测试和部署 Flue 智能体。

先决条件

你需要：

• 一个包含 Flue 项目的 GitLab 仓库
• 你的模型 provider key（例如 ANTHROPIC_API_KEY）

基本工作流

创建 .gitlab-ci.yml：

stages:
  - build
  - test
  - deploy

variables:
  NODE_ENV: production

build:
  stage: build
  image: node:22-slim
  script:
    - npm ci
    - npm run build
  artifacts:
    paths:
      - dist/
    expire_in: 1 hour
  cache:
    key: ${CI_COMMIT_REF_SLUG}
    paths:
      - node_modules/

test:
  stage: test
  image: node:22-slim
  script:
    - npm ci
    - npm test
  cache:
    key: ${CI_COMMIT_REF_SLUG}
    paths:
      - node_modules/

deploy:
  stage: deploy
  image: node:22-slim
  script:
    - npm ci
    - npm run build
    - # 你的部署命令在这里
  only:
    - main
  environment:
    name: production

使用 CI/CD 变量

在 GitLab 仓库设置中添加你的密钥：

1. 转到你的仓库 → Settings → CI/CD → Variables
2. 点击 “Add variable”
3. 添加你的 ANTHROPIC_API_KEY，确保勾选 “Masked” 和 “Protected”

在工作流中使用它：

build:
  stage: build
  image: node:22-slim
  script:
    - npm ci
    - npm run build
  variables:
    ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}

Docker 构建和推送

使用 Docker 构建并推送到容器注册表：

stages:
  - build
  - deploy

docker-build:
  stage: build
  image: docker:latest
  services:
    - docker:dind
  variables:
    DOCKER_IMAGE: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
  script:
    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
    - docker build -t $DOCKER_IMAGE .
    - docker push $DOCKER_IMAGE
  only:
    - main

部署到 Cloudflare

stages:
  - deploy

deploy-cloudflare:
  stage: deploy
  image: node:22-slim
  script:
    - npm ci
    - npm run build
    - npx wrangler deploy
  variables:
    CLOUDFLARE_API_TOKEN: $CLOUDFLARE_API_TOKEN
    CLOUDFLARE_ACCOUNT_ID: $CLOUDFLARE_ACCOUNT_ID
  only:
    - main

部署到 Fly.io

stages:
  - deploy

deploy-fly:
  stage: deploy
  image: flyio/flyctl:latest
  script:
    - flyctl deploy --remote-only
  variables:
    FLY_API_TOKEN: $FLY_API_TOKEN
  only:
    - main

运行测试

添加测试阶段：

test:
  stage: test
  image: node:22-slim
  script:
    - npm ci
    - npm test
  variables:
    ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}
  cache:
    key: ${CI_COMMIT_REF_SLUG}
    paths:
      - node_modules/

缓存依赖

使用缓存加速构建：

build:
  stage: build
  image: node:22-slim
  script:
    - npm ci
    - npm run build
  cache:
    key: ${CI_COMMIT_REF_SLUG}
    paths:
      - node_modules/

对于更精确的缓存：

build:
  stage: build
  image: node:22-slim
  script:
    - npm ci
    - npm run build
  cache:
    key:
      files:
        - package-lock.json
    paths:
      - node_modules/

矩阵构建

测试多个 Node.js 版本：

test:
  stage: test
  image: node:${NODE_VERSION}-slim
  parallel:
    matrix:
      - NODE_VERSION: ["18", "20", "22"]
  script:
    - npm ci
    - npm test
  cache:
    key: "${CI_COMMIT_REF_SLUG}-node-${NODE_VERSION}"
    paths:
      - node_modules/

部署环境

使用 GitLab 环境管理多个部署目标：

deploy-staging:
  stage: deploy
  script:
    - npm ci
    - npm run build
    - # 部署到 staging
  environment:
    name: staging
    url: https://staging.example.com
  only:
    - develop

deploy-production:
  stage: deploy
  script:
    - npm ci
    - npm run build
    - # 部署到 production
  environment:
    name: production
    url: https://example.com
  only:
    - main
  when: manual  # 手动触发生产部署

最佳实践

1. 使用 CI/CD 变量：永远不要在 .gitlab-ci.yml 中硬编码 API key。
2. 缓存依赖：使用 cache 关键字缓存 node_modules。
3. 使用工件：使用 artifacts 在作业之间共享构建输出。
4. 保护分支：使用 only 和 except 控制部署时机。
5. 使用环境：使用 GitLab 环境管理多个部署目标。

参考资料

• GitLab CI/CD 文档 — 官方 GitLab CI/CD 文档。
• GitLab CI/CD 变量 — 变量参考。
• Docker 部署 — 底层 Docker 镜像的详细信息。