<br /><br />

<p align="center"> <a href="https://www.middlewarehq.com/"><img src="https://yellow-cdn.veclightyear.com/0a4dffa0/99b11e47-e047-4ddf-a65a-9d80aed9d7d4.png" alt="Middleware Logo" width=300px></a> </p> <p align="center"><b>释放开发者潜力的开源工程管理工具</b></p> <p align="center"> <a href="https://github.com/middlewarehq/middleware/actions/workflows/build.yml"><img alt="持续集成" src="https://img.shields.io/github/actions/workflow/status/middlewarehq/middleware/build.yml?branch=main&label=build&style=for-the-badge"></a> <a href="https://github.com/middlewarehq/middleware/graphs/commit-activity"><img alt="每月提交活动" src="https://img.shields.io/github/commit-activity/m/middlewarehq/middleware?style=for-the-badge" /></a> <a href="https://github.com/middlewarehq/middleware/graphs/contributors"><img alt="贡献者" src="https://img.shields.io/github/contributors-anon/middlewarehq/middleware?color=yellow&style=for-the-badge" /></a> <br/> <a href="https://opensource.org/licenses/Apache-2.0"><img src="https://yellow-cdn.veclightyear.com/0a4dffa0/baa10733-7ab2-4e43-ac0a-359eedde78c6.svg?style=for-the-badge&label=license" alt="许可证" /></a> <img src="https://img.shields.io/github/stars/middlewarehq/middleware?style=for-the-badge" alt="星标" /> </p> <p align="center"><a href="https://mhq.link/oss-community">加入我们的开源社区</a></p>

简介

Middleware 是一款开源工具，旨在帮助工程领导者使用 DORA 指标 衡量和分析团队的效能。DORA 指标是一组四个关键值，用于洞察软件交付性能和运营效率。

这些指标包括：

• 部署频率：向生产环境或运营环境部署代码的频率。
• 变更前置时间：从提交到部署到生产环境所需的时间。
• 平均恢复时间：发生事故或故障后恢复服务所需的时间。
• 变更失败率：导致失败或需要修复的部署占比。

目录

• Middleware - 开源
  • 功能特性
  • 快速开始
    • 安装 Middleware
    • 故障排除
  • 开发者设置
    • 使用 Gitpod
    • 使用 Docker
    • 手动设置
  • 使用方法
  • 我们如何计算 DORA
  • 路线图
  • 贡献指南
  • 开发者自动化
  • 安全指南
  • 许可证

🚀 功能特性

• 集成各种 CI/CD 工具
• 自动收集和分析 DORA 指标
• 关键性能指标可视化
• 可定制的报告和仪表板
• 集成流行的项目管理平台

✨ 快速开始

⭐ 安装 Middleware

• 确保已安装并运行 docker。

• 打开终端并运行以下命令：

  docker volume create middleware_postgres_data
  docker volume create middleware_keys
  docker run --name middleware \
             -p 3333:3333 \
             -p 9696:9696 \
             -p 9697:9697 \
             -v middleware_postgres_data:/var/lib/postgresql/data \
             -v middleware_keys:/app/keys \
             -d middlewareeng/middleware:latest
  docker logs -f middleware

• 等待一段时间，让服务启动。

• 应用将在主机的 http://localhost:3333 上可用。

🛠️ 故障排除

1. 如果要停止容器，请运行以下命令：

   docker stop middleware

2. 要从远程获取最新版本并启动系统，请使用以下命令：

   docker pull middlewareeng/middleware:latest
   docker rm -f middleware || true
   docker run --name middleware \
              -p 3333:3333 \
              -v middleware_postgres_data:/var/lib/postgresql/data \
              -v middleware_keys:/app/keys \
              -d middlewareeng/middleware:latest
   docker logs -f middleware

3. 如果看到类似 Conflict. The container name "/middleware" is already in use by container 的错误。
   在再次运行容器之前，执行以下命令：

   docker rm -f middleware

4. 如果要删除容器中保存的所有数据，可以运行以下命令删除创建的卷：

   docker volume rm middleware_postgres_data middleware_keys

👩‍💻 开发者设置

☁️ 使用 GitPod

Gitpod 支持在远程机器上进行开发，如果您的机器不支持本地运行项目，它可以帮助您开始使用 Middleware。

如果您想在本地运行项目，可以使用 docker 进行设置或手动设置所有内容。

1. 点击下方按钮在 Gitpod 中打开此项目。

2. 这将在您的浏览器中打开一个配置完善的工作区，已安装所有必要的依赖项。

初始化后，您可以在 gitpod 实例的 3333 端口访问服务器。

🐳 使用 Docker

如果您尚未安装 Docker，请在此处安装 Docker。 确保 Docker 正在运行。

1. 克隆仓库：

   git clone https://github.com/middlewarehq/middleware

2. 进入项目目录：

   cd middleware

3. 在项目根目录运行 dev.sh 脚本 🪄
   ./dev.sh 会创建一个包含所需开发环境的 .env 文件，并运行一个 CLI，该 CLI 会完成从使用 docker compose watch 跟踪容器到提供不同服务日志的所有繁重工作。
   使用方法如下：

   ./dev.sh

   您可以更新 env.example 并设置 ENVIRONMENT=prod 以在生产环境中运行。
   如果需要对端口进行任何更改，可以相应地更新 docker-compose.yml 文件。

4. 访问应用程序： 项目运行后，通过网络浏览器访问 http://localhost:3333 来使用应用程序。 此外，其他服务可以通过以下方式访问：

   • 分析服务器可在 http://localhost:9696 访问。
   • 同步服务器可在 http://localhost:9697 访问。
   • PostgreSQL 数据库可通过以下方式访问：主机：localhost，端口：5434，用户名：postgres，密码：postgres，数据库名称：mhq-oss。
   • Redis 服务器可通过以下方式访问：主机：localhost，端口：6385。

5. 查看日志：尽管 CLI 会跟踪所有日志，但可以在不同的终端中使用以下命令查看容器内运行的服务日志：

   前端日志

   docker exec -it middleware-dev tail --lines 500 -f /var/log/web-server/web-server.log

   后端 API 服务器日志

   docker exec -it middleware-dev tail --lines 500 -f /var/log/apiserver/apiserver.log

   后端同步服务器日志

   docker exec -it middleware-dev tail --lines 500 -f /var/log/sync_server/sync_server.log

   Redis 日志

   docker exec -it middleware-dev tail --lines 500 -f /var/log/redis/redis.log

   PostgreSQL 日志

   docker exec -it middleware-dev tail --lines 500 -f /var/log/postgres/postgres.log

🛠️ 手动设置

要在本地设置 middleware，请按照以下步骤操作：

1. 克隆仓库：

   git clone https://github.com/middlewarehq/middleware.git

2. 进入项目目录：

   cd middleware

3. 运行 Redis 和 PostgreSQL 容器：

   如果您尚未安装 Docker，请在此处安装 Docker。

   运行以下命令使用 Docker 运行 PostgreSQL 和 Redis。

   cd database-docker && docker-compose up -d

   如果您不喜欢使用 Docker，可以选择手动安装 PostgreSQL 和 Redis。

   使用或开发 Middleware 完成后，您可以选择关闭这些正在运行的容器。（注意：如果您正在按照本文档操作并尝试运行 Middleware，请不要执行此操作。）

   cd database-docker/
   docker-compose down -v

4. 生成加密密钥：

   在项目根目录中运行以下命令生成项目的加密密钥：

   cd setup_utils && . ./generate_config_ini.sh && cd ..

5. 后端服务器设置

   • 安装 Python 版本 3.11.6

     • 如果您的机器上没有 Python，可以从这里安装。

     • 安装 pyenv

       git clone https://github.com/pyenv/pyenv.git ~/.pyenv

     • 将 pyenv 添加到您的 shell 配置文件（.bashrc、.bash_profile、.zshrc 等）：

       echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
       echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc

     • 重新加载您的 shell：

       source ~/.bashrc
       

   • 进入后端目录创建虚拟环境

     cd backend
     python -m venv venv

   • 激活虚拟环境

     . venv/bin/activate

   • 安装依赖

     pip install -r requirements.txt -r dev-requirements.txt

   • 在根目录创建一个 .env 文件，并添加以下环境变量，如果需要，请替换为您自己的值：

     DB_HOST=localhost
     DB_NAME=mhq-oss
     DB_PASS=postgres
     DB_PORT=5434
     DB_USER=postgres
     REDIS_HOST=localhost
     REDIS_PORT=6385
     ANALYTICS_SERVER_PORT=9696
     SYNC_SERVER_PORT=9697
     DEFAULT_SYNC_DAYS=31

   • 启动后端服务器

     • 切换到 analytics_server 目录

       cd analytics_server

     • 对于后端分析服务器：

       flask --app app --debug run --port 9696

     • 对于后端同步服务器：

       flask --app sync_app --debug run --port 9697

       注意：在启动分析服务器后，请在新的终端窗口中激活虚拟环境后再启动同步服务器。

6. Web 服务器设置

   • 安装 NodeJs 16.17 (LTS)，可以手动安装或使用 nvm 或 volta 等工具。

   • 安装 yarn 包管理器

     npm install --global yarn

   • 切换到 web-server 目录并安装软件包

     cd web-server
     yarn

   • 启动 web-server

     yarn dev

7. 访问应用程序： 项目运行后，通过网络浏览器访问 http://localhost:3333 来使用应用程序。
   此外：

   • 分析服务器可在 http://localhost:9696 访问。
   • 同步服务器可在 http://localhost:9697 访问。

🚀 使用方法

• 按照上述步骤设置项目。
• 从代码提供商生成并添加您的PAT令牌。
• 创建团队并为团队选择存储库。
• 查看团队的Dora指标。
• 更新与事故过滤器、排除的拉取请求、生产分支等相关的设置，以获得更准确的数据。

📖 我们如何计算DORA

Middleware可以仅使用GitHub数据显示DORA指标。目标是为所有使用Git数据的人提供DORA指标，而不考虑其他集成。

DORA指标源自拉取请求、部署和事故。

为简单起见，我们同步您的拉取请求数据，并将已回滚的拉取请求归类为事故，将已合并的拉取请求归类为部署。

变更前置时间

• 前置时间包括从第一次提交到PR开启的时间、首次响应时间、返工时间、合并时间和合并到部署时间。
• 在使用基于git的数据计算DORA时，PR合并被视为部署，因此合并到部署时间被视为0，而其他时间组成部分保持不变。

部署频率

• 此指标衡量代码变更部署到生产环境的频率。
• 当将PR合并视为部署时，这也可以表示PR合并的每日/每周/每月频率。

平均恢复时间（MTTR）

• MTTR衡量团队在生产环境发生故障后恢复服务的速度。
• 团队的平均事故解决时间用于计算其MTTR。
• 当将回滚PR视为事故时，事故的解决时间从原始PR合并到回滚PR合并的时间计算。

变更失败率（CFR）

• CFR量化导致生产环境服务中断或故障的变更百分比，有助于评估部署过程的稳定性和可靠性。
• CFR通过在一个时间间隔内将事故与部署关联来计算；每次部署可能有多个或没有事故。
• 可以与任何事故关联的部署被视为导致故障或中断。
• 使用导致中断的部署占总部署的比例来确定CFR。

🛣️ 路线图

即将推出！

❤️ 贡献指南

要开始为middleware做出贡献，请查看我们的CONTRIBUTING.md。

我们感谢您的贡献，并期待与您合作，使Middleware变得更好！

👨‍💻 开发者自动化

本节包含一些自动化脚本，可以生成样板代码以扩展某些功能并更快地发布 🚀

1. 在后端添加新设置

• 背景：最初，添加新设置需要了解设置系统的上下文，在一些文件中进行更改，并根据新设置类结构制作适配器和默认值。
• 现在可以通过在./backend/dev_scripts目录中运行python make_new_setting.py脚本来完成此操作

如果您在根目录中，可以运行：

python ./backend/dev_scripts/make_new_setting.py

• 以一致的格式输入设置名称。
• 添加所需的键及其类型。输入完所有字段后，输入done。
• 更新导入和代码格式。
• 您就可以开始了 :tada:
• 注意：对于设置中更复杂的非基本类型（如uuid、枚举等），您需要对生成的适配器进行修改。

https://github.com/middlewarehq/middleware/assets/70485812/f0529fa7-a2cb-44b1-ae07-2a7c97f56bef

⛓️ 安全指南

要开始为middleware做出贡献，请查看我们的SECURITY.md。

我们期待您在保持Middleware安全方面发挥作用！

许可证

本项目采用Apache 2.0许可证 - 有关详细信息，请参阅LICENSE.md文件。