释放开发者潜力的开源工程管理工具

Middleware 开源

简介

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

这些指标包括：

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

Middleware - 开源

🚀 功能特性

集成各种 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 上可用。

🛠️ 故障排除

如果要停止容器，请运行以下命令：
```
docker stop middleware
```

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

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

如果看到类似 Conflict. The container name "/middleware" is already in use by container 的错误。
在再次运行容器之前，执行以下命令：
```
docker rm -f middleware
```
如果要删除容器中保存的所有数据，可以运行以下命令删除创建的卷：
```
docker volume rm middleware_postgres_data middleware_keys
```

👩‍💻 开发者设置

☁️ 使用 GitPod

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

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

点击下方按钮在 Gitpod 中打开此项目。
这将在您的浏览器中打开一个配置完善的工作区，已安装所有必要的依赖项。

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

🐳 使用 Docker

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

克隆仓库：

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

进入项目目录：
```
cd middleware
```
在项目根目录运行 dev.sh 脚本 🪄
./dev.sh 会创建一个包含所需开发环境的 .env 文件，并运行一个 CLI，该 CLI 会完成从使用 docker compose watch 跟踪容器到提供不同服务日志的所有繁重工作。
使用方法如下：
```
./dev.sh
```
您可以更新 env.example 并设置 ENVIRONMENT=prod 以在生产环境中运行。
如果需要对端口进行任何更改，可以相应地更新 docker-compose.yml 文件。
访问应用程序：项目运行后，通过网络浏览器访问 http://localhost:3333 来使用应用程序。此外，其他服务可以通过以下方式访问：
- 分析服务器可在 http://localhost:9696 访问。
- 同步服务器可在 http://localhost:9697 访问。
- PostgreSQL 数据库可通过以下方式访问：主机：localhost，端口：5434，用户名：postgres，密码：postgres，数据库名称：mhq-oss。
- Redis 服务器可通过以下方式访问：主机：localhost，端口：6385。

查看日志：尽管 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，请按照以下步骤操作：

克隆仓库：

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

进入项目目录：
```
cd middleware
```
运行 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
```
生成加密密钥：

在项目根目录中运行以下命令生成项目的加密密钥：
```
cd setup_utils && . ./generate_config_ini.sh && cd ..
```
后端服务器设置
- 安装 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
```
    注意：在启动分析服务器后，请在新的终端窗口中激活虚拟环境后再启动同步服务器。
Web 服务器设置
- 安装 NodeJs 16.17 (LTS)，可以手动安装或使用 nvm 或 volta 等工具。
- 安装 yarn 包管理器
```
npm install --global yarn
```
- 切换到 web-server 目录并安装软件包
```
cd web-server
yarn
```
- 启动 web-server
```
yarn dev
```
访问应用程序：项目运行后，通过网络浏览器访问 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文件。