mqtt_power/DEPLOYMENT_GUIDE.md

CI/CD 部署指南 (OneDev + Docker Compose)

1. 简介

本文档旨在指导如何为 mqtt-charging-system 项目（包含 springboot-init-main 后端和 charging_web_app 前端）配置一套基于 OneDev 和 Docker Compose 的持续集成与持续部署 (CI/CD) 流程。实现目标是当代码提交到 OneDev 内置 Git 仓库的特定分支后，自动触发 OneDev 流水线，该流水线负责在部署服务器上构建应用 Docker 镜像，并使用 Docker Compose 重启包括数据库、MQTT Broker 和应用在内的所有服务。

采用技术栈：

• CI/CD 平台与代码仓库: OneDev (自建，包含内置 Git 服务)
• 构建与部署脚本: .onedev-buildspec.yml (OneDev 流水线定义)
• 容器化: Docker
• 服务编排: Docker Compose
• 部署目标: 运行 OneDev Agent 和 Docker 的 Linux 服务器

2. 先决条件

在开始配置此部署流程之前，请确保以下条件已满足：

• OneDev 服务器:
  • 已在一台服务器上成功安装并运行 OneDev 服务。参考 OneDev 官方文档 (https://onedev.io/docs/installation) 进行安装。
  • OneDev 服务器应具有足够的资源（CPU、内存、磁盘）。
• 线上应用/部署服务器 (OneDev Agent 服务器):
  • 一台 Linux 服务器，用于运行 OneDev Agent、构建 Docker 镜像以及通过 Docker Compose 运行所有服务容器 (数据库、Broker、后端、前端)。此服务器可以是 OneDev 服务器本身（不推荐用于生产），也可以是独立的机器。
  • 服务器已安装 Docker Engine, Docker Compose, 和 Git。
  • 服务器防火墙已配置，允许访问应用所需端口（例如后端 7529，前端 3000，MQTT 1883, 18083 等），以及 OneDev Agent 与 OneDev Server 通信的端口。
• 对 Docker, Docker Compose, Git, YAML 和 OneDev 有基本了解。

3. CI/CD 流程概览

1. 代码提交: 开发者将代码改动推送到 OneDev 内置 Git 仓库的 master 分支 (或其他配置的触发分支)。
2. OneDev 流水线触发: OneDev 检测到其内置仓库的变更，根据 .onedev-buildspec.yml 中的定义触发相应的流水线。
3. Agent 执行作业: OneDev Server 将流水线中的作业分配给匹配的 Agent (运行在部署服务器上)。
4. 流水线执行 (.onedev-buildspec.yml):
   • 检出代码: Agent 从仓库拉取最新的代码。
   • 构建应用 Docker 镜像: Agent 在本地构建后端和前端应用的新 Docker 镜像 (例如 mqtt-springboot-app:latest, mqtt-nextjs-app:latest)。
   • 准备 .env 文件: Agent 从 OneDev 项目配置的 Secrets 中获取敏感数据 (如数据库密码)，并生成 .env 文件。
   • 重启服务: Agent 使用项目中的 docker-compose.yml 和新生成的 .env 文件，通过 docker-compose 命令停止旧服务，并基于新的镜像和配置启动所有服务。
5. 监控与日志: 开发者可以在 OneDev 的 Web 界面上实时监控流水线执行状态、查看各步骤的详细日志。

4. 详细步骤

步骤 4.1: OneDev 服务器安装与配置

1. 安装 OneDev:
   • 访问 OneDev 官方文档 (https://onedev.io/docs/installation)，选择适合您环境的安装方法 (例如 Docker 运行，或直接部署 WAR 包)。
   • 强烈建议使用 Docker 运行 OneDev Server，方便管理和升级。官方文档提供了 Docker 命令示例。
   • 确保 OneDev 数据持久化配置正确。
2. 初始化 OneDev: 首次访问 OneDev URL，按照向导完成管理员账户设置和基本配置。

步骤 4.2: OneDev Agent 安装与配置 (在部署服务器上)

OneDev Agent 负责执行流水线中定义的作业。您可以选择直接在部署服务器上运行 Agent (通过 java -jar agent.jar ...)，或者更推荐的方式是 通过 Docker 容器运行 Agent。您已确认使用 Docker 容器运行 Agent。

1. 登录 OneDev: 使用管理员账户登录您的 OneDev 服务器。

2. 导航到 Agents 管理页面: 通常在 Administration -> Agents (或者新版可能是 Administration -> Job Executors)。

3. 连接新 Agent/Executor 指引: OneDev 界面会提供如何连接新 Agent/Executor 的指引。选择 "Connect an agent by running agent docker container" (或类似描述)。

4. 运行 Agent Docker 容器 (在部署服务器上):

   • OneDev 会提供一个 docker run 命令示例，类似如下 (请从您的 OneDev 界面复制准确命令，它会包含特定的服务器 URL 和 Agent 令牌):

     docker run --rm -v /var/run/docker.sock:/var/run/docker.sock -v <path_to_agent_data_on_host>:/opt/onedev/agent <onedev_agent_image> <OneDev Server URL> <Agent Token>
     

   • 关键参数解释:
     • --rm: 容器停止后自动删除 (可选，但常用于 Agent)。
     • -v /var/run/docker.sock:/var/run/docker.sock: 非常重要 (Docker-out-of-Docker - DooD)。这将宿主机的 Docker socket 挂载到 Agent 容器内部。这使得 Agent 容器可以控制宿主机的 Docker daemon 来执行 Docker 命令 (例如 docker build, docker-compose up)。我们当前的 .onedev-buildspec.yml 依赖此设置来在宿主机本地构建镜像和运行 Docker Compose。
     • -v <path_to_agent_data_on_host>:/opt/onedev/agent (或 OneDev 推荐的其他挂载点): 用于持久化 Agent 的配置和工作数据。例如，您可以设置为 -v /opt/onedev_agent_data:/opt/onedev/agent。
     • <onedev_agent_image>: OneDev 官方提供的 Agent Docker 镜像，例如 1dev/agent 或 onedev/agent (请参考 OneDev 界面的准确镜像名称)。
     • <OneDev Server URL> 和 <Agent Token>: 由您的 OneDev 服务器提供，用于 Agent 连接和认证。
   • Agent 容器所需的工具:
     • OneDev 官方的 Agent 镜像通常已包含 git。
     • 为了执行 .onedev-buildspec.yml 中的 docker-compose 命令，您需要确保 Agent 使用的 Docker 镜像内部也包含 docker-compose CLI (或者较新版本的 docker compose 插件)。如果官方 Agent 镜像不包含，您可能需要：
       • 在 .onedev-buildspec.yml 的 executeShell 步骤开始前，先在 Agent 容器内安装 docker-compose。
       • 或者，构建一个自定义的 Agent Docker 镜像，该镜像基于 OneDev 官方 Agent 镜像，并额外安装 docker-compose。
       • 或者，修改 .onedev-buildspec.yml 中的命令为 docker compose (注意空格)，如果 Agent 容器的 Docker CLI 支持 Compose V2 插件。
     • 我们当前的 .onedev-buildspec.yml 中的 executeShell 使用 docker-compose (带连字符)。

5. 为 Agent 添加标签:

   • Agent Docker 容器启动并成功连接到 OneDev Server 后，它会出现在 OneDev 的 Agents/Executors 列表中。
   • 点击该 Agent/Executor，进入其配置页面，添加一个标签，例如 agent-for-mqtt-power。这个标签将用于 .onedev-buildspec.yml 中的 agentMatcher，以确保作业在此 Agent 上运行。

6. 确保宿主机 Docker 环境: Agent 容器通过 DooD 控制宿主机的 Docker，所以确保部署服务器（宿主机）上已正确安装和配置了 Docker Engine 和 Docker Compose (如果 docker-compose.yml 依赖于宿主机上的 docker-compose CLI 版本特性)。

7. 持久化运行 Agent Docker 容器 (推荐):

   • 为了确保 Agent 在服务器重启后也能自动运行，建议使用 Docker 的重启策略或通过 systemd 管理 Agent Docker 容器的启动。
   • 使用 Docker 重启策略: 在 docker run 命令中添加 --restart unless-stopped 或 --restart always。

     docker run --restart unless-stopped --name onedev-agent-mqtt -d \
       -v /var/run/docker.sock:/var/run/docker.sock \
       -v /opt/onedev_agent_data_mqtt:/opt/onedev/agent \
       <onedev_agent_image> <OneDev Server URL> <Agent Token>
     

     • --name onedev-agent-mqtt: 为容器指定一个名称，方便管理。
     • -d: 后台运行容器。
   • 通过 systemd 管理 (更灵活，但略复杂): 您可以创建一个 systemd 服务单元来启动和管理这个 Agent Docker 容器。
     • 示例 (/etc/systemd/system/onedev-agent-docker.service):

       [Unit]
       Description=OneDev Agent Docker Container
       Requires=docker.service
       After=docker.service
       
       [Service]
       Restart=always
       ExecStartPre=-/usr/bin/docker stop onedev-agent-mqtt
       ExecStartPre=-/usr/bin/docker rm onedev-agent-mqtt
       ExecStart=/usr/bin/docker run --name onedev-agent-mqtt \
                   -v /var/run/docker.sock:/var/run/docker.sock \
                   -v /opt/onedev_agent_data_mqtt:/opt/onedev/agent \
                   <onedev_agent_image> <OneDev Server URL> <Agent Token>
       ExecStop=/usr/bin/docker stop onedev-agent-mqtt
       
       [Install]
       WantedBy=multi-user.target
       

       • 重要: 替换占位符。确保路径和镜像是正确的。
       • 然后 sudo systemctl daemon-reload, sudo systemctl start onedev-agent-docker, sudo systemctl enable onedev-agent-docker。

步骤 4.3: 在 OneDev 中创建项目并配置 Secrets

1. 创建项目:
   • 登录 OneDev，点击 + New Project。
   • 填写项目名称 (例如 mqtt-charging-system)。
   • 代码库:
     • 选择 Create an empty repository (如果您想在 OneDev 中开始一个全新的项目，并将 master 作为默认分支) 或 Import from an existing repository (如果您想将现有的 Git 仓库——例如本地的或之前 Gitea 上的，其主分支为 master——导入到 OneDev 中进行管理)。本项目将使用 OneDev 内置的 Git 服务。
   • (可选) 配置项目的默认分支为 master (如果通过导入创建且需要更改，或新建时指定)。
2. 配置项目 Secrets: 这些 Secrets 将被 .onedev-buildspec.yml 用于生成 .env 文件。
   • 进入项目 -> Settings -> Secrets。
   • 点击 New Secret。
   • 为每个需要的敏感信息创建一个 Secret。确保 Secret 名称与 .onedev-buildspec.yml 中 @secrets.<SecretName>@ 的 <SecretName> 部分完全一致。
     • MYSQL_ROOT_PASSWORD: 您的 MySQL root 密码。
     • MYSQL_DATABASE: 数据库名称 (例如 mqtt_power)。
     • MYSQL_USER: 应用连接数据库的用户名 (例如 appuser)。
     • MYSQL_PASSWORD: 应用连接数据库的密码。
     • (可选) EMQX_ADMIN_PASSWORD: 如果 EMQX 需要管理密码。
   • 勾选 Available to all branches (除非您有特定分支的特殊需求，例如只允许 master 分支的构建访问生产密码)。
   • 确保这些 Secrets 不允许在构建日志中显示。

步骤 4.4: 将项目代码和配置文件推送到仓库

1. 确保您的项目代码已克隆/推送到 OneDev 内置的 Git 仓库中，并且根目录包含以下文件：
   • .onedev-buildspec.yml: (已创建) 定义 CI/CD 流水线。
   • docker-compose.yml: (已创建和修改) 定义所有服务，应用镜像使用本地构建名称。
   • springboot-init-main/Dockerfile: (已创建) 用于构建后端镜像。
   • charging_web_app/Dockerfile: (已创建) 用于构建前端镜像。
   • springboot-init-main/src/main/resources/application.yml: (已修改) 数据库和 MQTT 连接信息通过环境变量配置。
2. 将这些文件提交并推送到 OneDev 内置 Git 仓库的 master 分支。

步骤 4.5: 触发与监控部署

1. 触发构建:
   • 当您向 OneDev 内置仓库的 master 分支 (或其他在 OneDev 项目构建设置中配置的触发分支) 推送代码时，OneDev 应该会自动触发 .onedev-buildspec.yml 中定义的流水线。
   • 您也可以在 OneDev 项目的 Builds 页面手动触发特定分支 (如 master) 的构建。
2. 监控构建:
   • 在 OneDev 项目的 Builds 页面，您可以看到正在运行和已完成的构建列表。
   • 点击特定的构建，可以查看其详细步骤、可视化流程、以及每个步骤的实时日志输出。
   • 如果构建失败，日志中会包含错误信息，帮助您排查问题。
3. 验证部署: 构建成功完成后，在部署服务器上：
   • 使用 docker ps -a 查看所有容器的状态。
   • 使用 docker-compose logs -f <service_name> (在 Agent 的工作区项目目录下) 或 docker logs <container_name_or_id> 查看各服务日志。
   • 尝试访问您的前端和后端应用。

5. .onedev-buildspec.yml 文件详解 (关键点)

(已在之前创建，此处为回顾和说明)

• version: 8: 指定 buildspec 的版本。
• jobs: 定义一个或多个作业。
  • name: 作业的名称。
  • agentMatcher: 指定运行此作业的 Agent 必须拥有的标签 (例如 agent-for-mqtt-power)。
  • steps: 作业中执行的步骤。
    • checkout: 检出代码到 Agent 的工作区。
    • setupVariables: 定义变量，可以引用 Secrets (@secrets.MySecret@) 或其他 OneDev 内置变量 (@commit_hash@ 等)。
    • buildImage: OneDev 内置步骤，用于构建 Docker 镜像。
      • dockerfile: Dockerfile 的路径。
      • imageName, imageTag: 构建的镜像名称和标签。
      • buildPath: Docker build context 路径。
    • writeFile: 将内容写入 Agent 工作区的文件 (例如生成 .env 文件)。
    • executeShell: 执行 shell 命令 (例如 docker-compose up -d)。
  • dependencies: 定义作业之间的依赖关系 (例如，部署作业依赖于构建作业)。
  • triggers: 定义触发作业的条件 (例如，特定路径的文件变更、其他作业成功等)。

6. 回滚策略

• 重新运行旧的成功构建: OneDev 保存了所有构建的历史记录。如果新部署出现问题，您可以找到上一个基于 master 分支的成功部署构建，并点击 "Rebuild" (或类似选项) 来重新运行该构建，从而回滚到之前的状态。
• 代码回滚并触发新构建: 在 Git 中将 master 分支的代码回滚到某个稳定版本，然后推送到 OneDev，OneDev 将会基于旧代码重新构建和部署。
• (如果镜像打了 commit hash 标签): 如果您的镜像标签包含 commit hash (例如 @commit_hash@变量)，并且您知道某个稳定版本的 commit hash，理论上可以手动修改部署服务器上的 docker-compose.yml (或通过 OneDev 参数化构建传递镜像标签) 来指向旧镜像并重启，但这通常不如通过 OneDev 流水线管理方便。

7. 注意事项与常见问题

• Agent 资源与权限: 确保 OneDev Agent 运行的用户有足够的权限（特别是 Docker 命令执行权限）和系统资源（CPU, 内存, 磁盘空间）来完成构建和部署任务。
• Secrets 管理: 严格管理 OneDev 中的 Secrets，不要在日志中暴露它们。
• .onedev-buildspec.yml 语法: YAML 格式对缩进敏感，编写时需注意。
• Docker 构建上下文: buildImage 步骤中的 buildPath 很重要，它决定了 Docker 构建时的上下文环境。
• 网络配置: 确保 OneDev Server, OneDev Agent, 以及部署服务器上的 Docker 容器之间网络通畅。
• 首次构建: 第一次触发构建时，请密切关注 OneDev 中的日志，以便快速定位和解决可能出现的配置问题。
• 日志: OneDev 提供了非常详细的构建日志，是排查问题的首要工具。

---

本文档提供了使用 OneDev (及其内置 Git 服务) 和 Docker Compose 配置 CI/CD 的框架。OneDev 提供了强大的可视化管理和流水线定义能力，可以显著简化部署流程的管理和监控。