跳到主要内容

C0726D02-开发手册

项目名称：C0726​

一、项目概述​

C0726 是一个面向微服务架构的现代化项目，采用 Gitea 作为代码托管平台，Harbor 作为镜像仓库，利用内网资源提高构建速度，并通过 Gitea Actions 实现完整的 CI/CD 流水线部署机制。项目强调私有化部署、安全隔离和 DevOps 自动化能力。

二、代码仓管理​

项目代码使用 Gitea 进行版本控制，建议优先使用内网地址以提升访问速度。

  • Gitea 内网地址: https://git.in.greenshadecapital.com
  • Gitea 外网地址: https://git.greenshadecapital.site

分支规范​

分支名称说明
main生产环境主干
dev日常开发分支
feature/*新功能开发分支
hotfix/*热修复分支

三、配置管理​

项目使用 Gitea 中的独立仓库作为配置仓，采用 JSON 格式进行集中管理：

  • 所有配置文件统一存放在名为 c0726-config 的仓库中；
  • 配置文件必须通过审核后方可合并；
  • 不允许在配置中包含密钥或敏感信息，密钥请统一由 Secrets 管理。

四、容器镜像管理（Harbor）​

镜像仓库地址​

Harbor 仓库统一部署在云服务器上，专为本项目服务：

  • 地址：https://docker-repo.pleuston.org
  • 项目名：c0726
  • 登录方式：使用项目分配账号（建议绑定 2FA）

镜像命名规范​

docker-repo.pleuston.org/c0726/<模块名>:<tag>

示例：

docker-repo.pleuston.org/c0726/api-server:1.0.0
docker-repo.pleuston.org/c0726/web-client:latest

Tag 使用约定​

标签名用途说明
latest用于本地测试
1.0.0正式版本（语义化）
dev-20250727开发分支构建版本

五、CI/CD 流水线说明​

工具平台​

CI/CD 基于 Gitea Actions 实现，支持构建镜像、推送 Harbor、远程部署。

触发机制​

  • 提交到 main 或 dev 分支会自动触发流水线。
  • 提交信息包含 [skip ci] 可跳过本次流水线。

示例工作流文件（.gitea/workflows/deploy.yml）​

name: Deploy to Dev

on:
  push:
    branches:
      - dev

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout Code
        uses: actions/checkout@v3

      - name: Login to Harbor
        run: |
          echo "${{ secrets.HARBOR_PASSWORD }}" | docker login docker-repo.pleuston.org -u ${{ secrets.HARBOR_USERNAME }} --password-stdin

      - name: Build and Push Docker Image
        run: |
          docker build -t docker-repo.pleuston.org/c0726/api-server:dev-${{ github.sha }} .
          docker push docker-repo.pleuston.org/c0726/api-server:dev-${{ github.sha }}

      - name: Deploy to Remote Server
        run: |
          sshpass -p "${{ secrets.SSH_PASSWORD }}" ssh -o StrictHostKeyChecking=no root@192.168.1.10 "
            docker pull docker-repo.pleuston.org/c0726/api-server:dev-${{ github.sha }} &&
            docker stop api-server || true &&
            docker rm api-server || true &&
            docker run -d --name api-server -p 8000:8000 docker-repo.pleuston.org/c0726/api-server:dev-${{ github.sha }}
          "

六、密钥与认证管理​

为确保安全，所有密钥与访问凭据需通过 Gitea Secrets 管理：

建议 Secrets 配置项​

Secret 名称用途说明
HARBOR_USERNAMEHarbor 登录用户名
HARBOR_PASSWORDHarbor 登录密码
SSH_PASSWORD远程服务器密码（推荐用 SSH Key）
DEPLOY_HOST远程部署目标主机 IP

密钥不得以明文形式存在于代码中或配置文件中。

七、开发与部署流程​

  1. 开发者从 main 创建 feature/* 分支进行开发；
  2. 开发完成后提交 PR 合并至 dev；
  3. CI/CD 自动构建并部署至测试环境；
  4. 测试通过后，合并 dev → main；
  5. CI/CD 自动构建并部署至生产环境；
  6. 版本发布记录需归档于 Gitea Releases 页。

八、安全规范​

  • 所有仓库须开启分支保护，需 PR 审核；
  • Harbor 镜像应限制权限，仅允许 push 拉取；
  • 禁止将 .env 文件、私钥、配置上传到 Gitea；
  • 建议所有开发者启用 2FA 登录 Gitea 和 Harbor；
  • 配置自动化镜像扫描，及时发现漏洞。

九、其他说明​

  • 服务器部署任务需由 DevOps 人员审核后执行；
  • 推荐统一使用内网地址加快构建与部署效率；
  • CI/CD 失败请第一时间查看日志并通知管理员；
  • 如有新模块需引入 Harbor 镜像仓，请通知管理员进行项目分配。

十、联系方式​