OneAPI CI/CD流水线：GitHub Actions自动化构建Docker镜像

1. 项目概述

OneAPI 是一个强大的大模型 API 管理与分发系统，它通过统一的 OpenAI API 格式让你能够访问几乎所有主流的大语言模型。这意味着你只需要一套代码，就能调用包括 OpenAI、Azure、Anthropic Claude、Google Gemini、DeepSeek、字节豆包、ChatGLM、文心一言等在内的数十种模型。

这个项目的核心价值在于简化了多模型管理的复杂性。无论你是开发者还是企业用户，都不需要为每个模型单独编写适配代码，也不需要管理多个 API 密钥和端点。OneAPI 提供了一个统一的接口，让你的应用能够无缝切换和使用不同的大模型服务。

通过 Docker 镜像部署，OneAPI 实现了开箱即用的体验。单可执行文件的设计让部署变得极其简单，你可以在几分钟内就搭建起自己的大模型网关服务。

2. 核心功能特性

2.1 多模型统一支持

OneAPI 最强大的功能之一是它对各种大模型的广泛支持。目前已经集成了超过 30 种主流的大语言模型，包括：

  • 国际模型：OpenAI ChatGPT 系列、Anthropic Claude、Google PaLM2/Gemini、Mistral、Cohere 等
  • 国内模型：字节豆包、百度文心一言、阿里通义千问、讯飞星火、智谱 ChatGLM、360 智脑、腾讯混元等
  • 新兴模型：Moonshot AI、百川大模型、零一万物、阶跃星辰等
  • 自部署模型：支持 Ollama 等本地部署的模型

这种多模型支持意味着你可以根据需求灵活选择最适合的模型，或者在多个模型之间进行负载均衡，确保服务的稳定性和性能。

2.2 高级管理功能

除了基本的模型调用，OneAPI 还提供了一系列企业级的管理功能：

用户与权限管理：

  • 完整的用户系统，支持多种登录方式（邮箱、GitHub、飞书、微信公众号）
  • 用户分组和权限控制，可以设置不同的访问权限和费率
  • 邀请奖励机制，促进用户增长

资源管理：

  • 令牌管理：可以设置 API 令牌的过期时间、使用额度、IP 白名单和模型访问权限
  • 兑换码系统：支持批量生成和管理充值兑换码
  • 额度明细查询：清晰展示所有额度的使用情况

渠道管理：

  • 多渠道负载均衡：自动在多个模型提供商之间分配请求
  • 渠道分组和倍率设置：可以为不同用户组设置不同的计费标准
  • 失败自动重试：提高请求的成功率

2.3 自定义与扩展能力

OneAPI 提供了丰富的自定义选项，让你能够根据需求调整系统：

  • 界面自定义：可以修改系统名称、LOGO、页脚内容，完全自定义首页和关于页面
  • API 扩展：通过管理 API 可以在不修改源代码的情况下扩展系统功能
  • 主题切换：支持多种界面主题，可以根据喜好进行切换
  • Webhook 集成：可以与 Message Pusher 等系统集成，实现消息推送和报警

3. 安全注意事项

在使用 OneAPI 时，安全应该是首要考虑的因素。系统初次部署后，有一个非常重要的安全步骤需要立即执行：

重要安全提示：使用 root 用户初次登录系统后，务必立即修改默认密码 123456！保持默认密码会带来严重的安全风险，可能导致未授权访问和数据泄露。

建议采取以下安全最佳实践：

  1. 强密码策略：设置包含大小写字母、数字和特殊字符的复杂密码
  2. 定期更换密码：建议每 3-6 个月更换一次管理员密码
  3. 网络隔离：将 OneAPI 部署在内网环境，通过反向代理提供外部访问
  4. 定期更新：保持系统更新到最新版本，获取安全补丁和新功能

4. GitHub Actions CI/CD 流水线配置

下面我们来详细讲解如何为 OneAPI 项目配置 GitHub Actions 自动化构建流水线。这个流水线会自动构建 Docker 镜像并推送到镜像仓库。

4.1 基础工作流配置

首先在你的 OneAPI 项目根目录创建 .github/workflows/docker-build.yml 文件：

name: Build and Push Docker Image

on:
  push:
    branches: [ main ]
    tags: [ 'v*' ]
  pull_request:
    branches: [ main ]

env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}

jobs:
  build-and-push:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write

    steps:
    - name: Checkout code
      uses: actions/checkout@v4

    - name: Set up Docker Buildx
      uses: docker/setup-buildx-action@v3

    - name: Log in to GitHub Container Registry
      uses: docker/login-action@v3
      with:
        registry: ${{ env.REGISTRY }}
        username: ${{ github.actor }}
        password: ${{ secrets.GITHUB_TOKEN }}

    - name: Extract metadata for Docker
      id: meta
      uses: docker/metadata-action@v5
      with:
        images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}

    - name: Build and push Docker image
      uses: docker/build-push-action@v5
      with:
        context: .
        push: ${{ github.event_name != 'pull_request' }}
        tags: ${{ steps.meta.outputs.tags }}
        labels: ${{ steps.meta.outputs.labels }}

这个基础配置实现了以下功能：

  • 在推送到 main 分支或创建版本标签时触发构建
  • 使用 GitHub Container Registry 作为镜像仓库
  • 自动提取元数据生成合适的镜像标签
  • 只在非 PR 事件时推送镜像

4.2 多架构构建支持

为了让你的 Docker 镜像支持多种硬件架构，可以添加多架构构建支持：

- name: Set up QEMU
  uses: docker/setup-qemu-action@v3
  with:
    platforms: arm64,arm

- name: Build and push multi-arch image
  uses: docker/build-push-action@v5
  with:
    context: .
    platforms: linux/amd64,linux/arm64
    push: ${{ github.event_name != 'pull_request' }}
    tags: |
      ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest
      ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.sha }}
    cache-from: type=gha
    cache-to: type=gha,mode=max

多架构构建让你的镜像可以在 Intel/AMD 处理器和 ARM 处理器（如 Apple Silicon Mac、树莓派等）上运行，大大提高了兼容性。

4.3 添加测试和扫描步骤

为了确保镜像质量，建议在构建过程中添加测试和安全扫描：

- name: Run unit tests
  run: |
    # 这里添加你的测试命令
    echo "Running tests..."

- name: Scan for vulnerabilities
  uses: aquasecurity/trivy-action@master
  with:
    image-ref: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest
    format: table
    exit-code: '1'
    ignore-unfixed: true
    vuln-type: 'os,library'
    severity: 'CRITICAL,HIGH'

安全扫描可以帮助你发现镜像中的已知漏洞，确保部署的安全性。

4.4 完整的工作流示例

下面是一个完整的 GitHub Actions 工作流配置，包含了构建、测试、扫描和多架构支持：

name: OneAPI Docker CI/CD

on:
  push:
    branches: [ main ]
    tags: [ 'v*' ]
  pull_request:
    branches: [ main ]
  workflow_dispatch:

env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}

jobs:
  docker-build:
    name: Build and Push Docker Image
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write

    steps:
    - name: Checkout code
      uses: actions/checkout@v4

    - name: Set up Docker Buildx
      uses: docker/setup-buildx-action@v3

    - name: Set up QEMU
      uses: docker/setup-qemu-action@v3

    - name: Log in to GitHub Container Registry
      uses: docker/login-action@v3
      with:
        registry: ${{ env.REGISTRY }}
        username: ${{ github.actor }}
        password: ${{ secrets.GITHUB_TOKEN }}

    - name: Extract metadata for Docker
      id: meta
      uses: docker/metadata-action@v5
      with:
        images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
        tags: |
          type=raw,value=latest,enable=${{ github.ref == format('refs/heads/{0}', 'main') }}
          type=sha,prefix=,suffix=,format=long

    - name: Build and push Docker image
      uses: docker/build-push-action@v5
      with:
        context: .
        platforms: linux/amd64,linux/arm64
        push: ${{ github.event_name != 'pull_request' }}
        tags: ${{ steps.meta.outputs.tags }}
        labels: ${{ steps.meta.outputs.labels }}
        cache-from: type=gha
        cache-to: type=gha,mode=max

    - name: Vulnerability scan
      if: github.event_name != 'pull_request'
      uses: aquasecurity/trivy-action@master
      with:
        image-ref: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest
        format: sarif
        output: trivy-results.sarif
        exit-code: '0'

    - name: Upload vulnerability scan results
      if: always() && github.event_name != 'pull_request'
      uses: github/codeql-action/upload-sarif@v3
      with:
        sarif_file: trivy-results.sarif

  test-deployment:
    name: Test Deployment
    runs-on: ubuntu-latest
    needs: docker-build
    if: github.event_name != 'pull_request'

    steps:
    - name: Checkout code
      uses: actions/checkout@v4

    - name: Test Docker deployment
      run: |
        docker run -d --name oneapi-test -p 3000:3000 \
          -e SQL_DSN="sqlite:///data/oneapi.db" \
          ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest
        sleep 10
        curl -f http://localhost:3000/ || exit 1
        docker stop oneapi-test
        docker rm oneapi-test

这个完整的工作流提供了：

  • 多架构 Docker 镜像构建和推送
  • 漏洞扫描和结果上传
  • 部署测试验证
  • 缓存优化加快构建速度

5. Dockerfile 优化建议

为了充分发挥 CI/CD 流水线的优势，你的 Dockerfile 也需要进行相应优化：

# 构建阶段
FROM golang:1.21-alpine AS builder
WORKDIR /app
COPY . .
RUN go mod download
RUN CGO_ENABLED=0 GOOS=linux go build -o oneapi .

# 运行阶段
FROM alpine:latest
RUN apk --no-cache add ca-certificates
WORKDIR /root/
COPY --from=builder /app/oneapi .
COPY --from=builder /app/templates ./templates
COPY --from=builder /app/static ./static

# 创建数据目录
RUN mkdir -p /data

# 设置环境变量
ENV SQL_DSN=sqlite:///data/oneapi.db
ENV PORT=3000
ENV TZ=Asia/Shanghai

# 暴露端口
EXPOSE 3000

# 启动应用
CMD ["./oneapi"]

这个 Dockerfile 使用了多阶段构建，最终镜像只包含运行所需的文件，体积更小，安全性更高。

6. 部署和使用指南

6.1 快速部署命令

使用自动化构建的镜像部署 OneAPI 非常简单：

docker run -d \
  --name oneapi \
  -p 3000:3000 \
  -v /path/to/data:/data \
  -e SQL_DSN="sqlite:///data/oneapi.db" \
  ghcr.io/your-username/oneapi:latest

这个命令会启动一个 OneAPI 实例，数据将持久化在宿主机的 /path/to/data 目录中。

6.2 环境变量配置

OneAPI 支持通过环境变量进行配置，常用的配置选项包括：

# 数据库配置
SQL_DSN="sqlite:///data/oneapi.db"

# 服务配置
PORT=3000
TZ=Asia/Shanghai

# 安全配置
SESSION_SECRET=your-secret-key
ENCRYPTION_KEY=your-encryption-key

# 邮件配置（用于用户注册和密码重置）
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USERNAME=your-email@example.com
SMTP_PASSWORD=your-password

6.3 反向代理配置

在生产环境中，建议使用 Nginx 或 Caddy 作为反向代理：

# Nginx 配置示例
server {
    listen 80;
    server_name your-domain.com;
    
    location / {
        proxy_pass http://localhost:3000;
        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;
    }
}

7. 总结

通过 GitHub Actions CI/CD 流水线，你可以实现 OneAPI 项目的自动化构建、测试和部署。这种方法带来了多个显著优势：

效率提升：自动化构建流程减少了手动操作，提高了开发效率。每次代码变更都会自动触发构建和测试，确保代码质量。

一致性保证：Docker 镜像确保了运行环境的一致性，避免了"在我机器上能运行"的问题。多架构支持让应用可以在不同硬件平台上稳定运行。

安全性增强：自动化的安全扫描和测试可以帮助发现潜在的安全问题。漏洞扫描结果会直接集成到 GitHub 的安全报告中。

可维护性改善：完整的 CI/CD 流程让项目更易于维护和协作。部署测试确保了每次构建的镜像都是可用的。

通过本文介绍的配置方法，你可以为自己的 OneAPI 项目搭建一个完整的自动化构建流水线，享受现代化开发流程带来的便利和可靠性。

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。

Logo
https://edu.csdn.net/learn/39067/627173?utm_source=2019755004

汇聚全球AI编程工具，助力开发者即刻编程。

更多推荐

cover

一个 API 入口调用多个大模型：AiiOnly客户端 + CC Switch 打通 Codex AI编程流程

avatar AI编程社区
cover

VSCode Claude Code + MiMo 中转免登录完整配置教程（解决原生登录弹窗 + 模型报错）

avatar AI编程社区
cover

从零开始做一个属于自己的 Skill（保姆级教程）

avatar AI编程社区