From 55addea6942ee0325f47c8a83342e1db50483061 Mon Sep 17 00:00:00 2001 From: hezhaohui Date: Wed, 22 Jul 2026 10:13:57 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E9=87=8D=E5=86=99=20README.md=EF=BC=8C?= =?UTF-8?q?=E5=AE=8C=E5=96=84=E9=A1=B9=E7=9B=AE=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增项目徽章（License、Go、Vue、Element Plus、PRs Welcome） - 重写核心能力板块：资源纳管、基础服务部署、业务交付、统一认证与审计 - 完善技术栈表格，增加说明列 - 扩充项目结构目录，覆盖前后端完整模块 - 优化快速开始指南，新增构建与部署说明 - 补充 API 文档、开发指南、Git 提交规范 - 新增参与贡献、路线图、许可证等板块 --- README.md | 278 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 186 insertions(+), 92 deletions(-) diff --git a/README.md b/README.md index f0dcb82..eda0a07 100644 --- a/README.md +++ b/README.md @@ -1,126 +1,220 @@ -# XINFRA - 统一运维入口平台 +
-XINFRA 是一个统一运维入口平台，整合多个运维子系统，提供统一的登录认证、子系统导航、审计日志和 Ansible 运维调度功能。 +# XINFRA -## 项目特性 +**统一运维入口平台** -- 🔐 **统一认证**：支持 LDAP + SAML + OAuth 2.0 认证 -- 🎯 **子系统导航**：卡片式展示 6 个运维子系统，支持 SSO 跳转 -- 📊 **审计面板**：登录审计 + 运维操作审计，完整的操作追溯 -- 🚀 **Ansible 调度**：Playbook 执行、实时日志推送 -- 🔒 **安全可靠**：JWT 认证、HTTPS 传输、敏感配置 K8s Secret 管理 +一站式资源纳管、基础服务部署与业务交付平台，整合多个运维子系统，为团队提供统一的认证、权限、审计和运维操作入口。 -## 技术栈 +[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE) +[![Go Version](https://img.shields.io/badge/go-1.21+-00ADD8.svg?logo=go)](https://go.dev/) +[![Vue Version](https://img.shields.io/badge/vue-3.3+-42b883.svg?logo=vue.js)](https://vuejs.org/) +[![Element Plus](https://img.shields.io/badge/element--plus-2.3+-409EFF.svg)](https://element-plus.org/) +[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](http://makeapullrequest.com) -| 层级 | 技术 | -|------|------| -| 后端 | Go 1.21+ / Gin | -| 前端 | Vue 3.3+ / Element Plus / Vite | -| 数据库 | MySQL 8.0 | -| 缓存 | Redis | -| 部署 | Kubernetes + Nginx | +
-## 项目结构 +--- + +## ✨ 核心能力 + +### 📦 资源纳管 + +- **多集群管理** — 统一接入和管理多个 K8s 集群，集群状态实时可见 +- **资源全景** — 纳管集群内的 Namespace、工作负载、配置等核心资源，提供统一视图 +- **租户管理** — 基于业务线的多租户资源隔离与配额管理 + +### 🚀 基础服务部署 + +- **服务目录** — 标准化的服务目录管理，定义和维护可部署的服务清单 +- **服务发布** — 基于 Wayne 平台的 K8s 服务部署与发布，支持多环境发布 +- **运维驾驶舱** — 服务状态总览，实时掌握部署进度与运行状况 + +### 🎯 业务交付 + +- **业务线管理** — 按业务线组织资源与权限，清晰的组织架构映射 +- **子系统授权** — 基于业务线的细粒度子系统访问控制与角色绑定 +- **任务调度** — 统一的任务中心，编排和执行运维操作流程 + +### 🔐 统一认证与审计 + +- **多协议认证** — LDAP + SAML + OAuth 2.0，对接企业统一身份认证 +- **SSO 单点登录** — 一次登录，无缝跳转各子系统 +- **全链路审计** — 登录审计 + 操作审计，完整记录每一次运维操作 + +## 🛠️ 技术栈 + +| 层级 | 技术 | 说明 | +|:---:|------|------| +| **前端** | Vue 3 + TypeScript + Vite | Composition API + Element Plus UI | +| **后端** | Go + Gin + GORM | RESTful API + Swagger 文档 | +| **数据库** | MySQL 8.0 | GORM AutoMigrate 迁移管理 | +| **认证** | JWT + LDAP/SAML/OAuth 2.0 | 多协议统一认证网关 | +| **部署** | Docker + Kubernetes + Wayne | Nginx 反向代理 + K8s 编排 | + +## 📁 项目结构 ``` xinfra/ -├── frontend/ # 前端 Vue 3 项目 -│ ├── src/ -│ │ ├── api/ # API 请求封装 -│ │ ├── components/ # 可复用组件 -│ │ ├── composables/ # 组合式函数 -│ │ ├── layouts/ # 页面布局 -│ │ ├── router/ # 路由配置 -│ │ ├── stores/ # Pinia 状态管理 -│ │ ├── views/ # 页面视图 -│ │ └── utils/ # 工具函数 -│ └── ... -├── server/ # 后端 Go 项目 -│ ├── cmd/ # 程序入口 -│ ├── internal/ # 内部包（分层架构） -│ ├── pkg/ # 可复用公共包 -│ └── migrations/ # 数据库迁移 -├── deploy/ # 部署配置 -│ ├── docker/ # Docker 构建配置 -│ └── k8s/ # Kubernetes 配置 -├── docs/ # 项目文档 -└── ... +├── frontend/ # 前端 Vue 3 项目 +│ └── src/ +│ ├── api/ # API 请求封装 +│ ├── components/ # 可复用组件 +│ ├── composables/ # 组合式函数 +│ ├── layouts/ # 页面布局 +│ ├── router/ # 路由配置 +│ ├── stores/ # Pinia 状态管理 +│ ├── views/ # 页面视图 +│ │ ├── dashboard/ # 运维驾驶舱 +│ │ ├── cluster/ # 集群管理 +│ │ ├── resource/ # 资源纳管（Namespace/租户/状态看板） +│ │ ├── service/ # 服务部署（目录/发布管理） +│ │ ├── task/ # 任务调度中心 +│ │ ├── businessLine/ # 业务线管理 +│ │ ├── subsystem/ # 子系统管理与授权 +│ │ ├── config/ # 配置管理 +│ │ ├── monitor/ # 监控告警 +│ │ ├── audit/ # 审计日志 +│ │ └── auth/ # 登录认证 +│ └── utils/ # 工具函数 +├── server/ # 后端 Go 项目 +│ ├── cmd/server/ # 程序入口 +│ ├── internal/ # 内部包（分层架构） +│ │ ├── auth/ # 认证模块 +│ │ ├── config/ # 配置管理 +│ │ ├── database/ # 数据库连接 +│ │ ├── handler/ # HTTP 处理器 +│ │ ├── model/ # 数据模型 +│ │ ├── router/ # 路由注册 +│ │ ├── service/ # 业务逻辑 +│ │ ├── sso/ # SSO 单点登录 +│ │ └── wayne/ # Wayne 子系统集成 +│ └── migrations/ # 数据库迁移 +├── deploy/ # 部署配置 +│ ├── docker/ # Docker 构建配置 +│ └── k8s/ # Kubernetes 配置 +├── Makefile # 构建脚本 +└── LICENSE # Apache 2.0 License ``` -## 快速开始 +## 🚀 快速开始 ### 环境要求 -- Go 1.21+ -- Node.js 18+ -- MySQL 8.0 -- Redis 7.0+ +| 依赖 | 版本 | +|------|------| +| Go | >= 1.21 | +| Node.js | >= 18 | +| MySQL | >= 8.0 | +| Redis | >= 7.0 | -### 本地开发 +### 安装与运行 -1. 克隆项目 - ```bash - git clone - cd xinfra - ``` +```bash +# 1. 克隆项目 +git clone https://github.com/2311719626/xinfra.git +cd xinfra -2. 启动开发环境 - ```bash - make dev-up - ``` +# 2. 启动本地开发环境（MySQL + Redis） +make dev-up -3. 启动前端开发服务器 - ```bash - make run-frontend - ``` +# 3. 启动前后端开发服务器 +make run +``` -4. 启动后端开发服务器 - ```bash - make run-server - ``` +> 💡 也可以分别启动前后端： +> ```bash +> make run-frontend # 启动前端 dev server +> make run-server # 启动后端 server +> ``` -### 构建部署 +### 构建与部署 -1. 构建项目 - ```bash - make build - ``` +```bash +# 构建前后端 +make build -2. 构建 Docker 镜像 - ```bash - make docker - ``` +# 构建 Docker 镜像 +make docker -3. 部署到 Kubernetes - ```bash - kubectl apply -f deploy/k8s/ - ``` +# 部署到 Kubernetes +kubectl apply -f deploy/k8s/ +``` -## 开发规范 +## 📖 API 文档 + +Swagger 文档通过 [swaggo](https://github.com/swaggo/swag) 自动生成： + +```bash +make swagger +``` + +生成后访问：`http://localhost:8080/swagger/index.html` + +## 🔧 开发指南 + +### 可用命令 + +| 命令 | 说明 | +|------|------| +| `make help` | 显示帮助信息 | +| `make build` | 构建前后端项目 | +| `make run` | 启动开发服务器 | +| `make test` | 运行测试 | +| `make docker` | 构建 Docker 镜像 | +| `make swagger` | 生成 API 文档 | +| `make migrate-up` | 执行数据库迁移 | +| `make migrate-down` | 回滚数据库迁移 | +| `make clean` | 清理构建产物 | ### Git 提交规范 -使用语义化提交信息： -- `feat:` 新功能 -- `fix:` 修复 bug -- `docs:` 文档更新 -- `style:` 代码格式调整 -- `refactor:` 重构 -- `test:` 测试相关 -- `chore:` 构建/工具相关 +本项目遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范： + +| 前缀 | 说明 | +|------|------| +| `feat:` | ✨ 新功能 | +| `fix:` | 🐛 修复 Bug | +| `docs:` | 📝 文档更新 | +| `style:` | 💄 代码格式（不影响逻辑） | +| `refactor:` | ♻️ 重构 | +| `perf:` | ⚡ 性能优化 | +| `test:` | ✅ 测试相关 | +| `chore:` | 🔧 构建/工具链 | +| `ci:` | 🎡 CI/CD 配置 | ### 代码规范 -- Go 代码遵循 `gofmt` 格式 -- Vue/TypeScript 代码遵循 ESLint 规范 -- 提交前请确保代码通过所有测试 +- **Go** — 遵循 `gofmt` 格式，提交前运行 `go vet ./...` +- **Vue/TypeScript** — 遵循 ESLint 规范，提交前运行 `npm run lint` +- 提交前请确保代码通过所有测试：`make test` -## 相关文档 +## 🤝 参与贡献 -- [MVP 方案文档](docs/mvp-skeleton-plan.md) -- [API 接口文档](docs/api.md)（待补充） -- [部署文档](docs/deployment.md)（待补充） +欢迎参与贡献！请遵循以下步骤： -## 许可证 +1. Fork 本仓库 +2. 创建特性分支：`git checkout -b feat/amazing-feature` +3. 提交更改：`git commit -m 'feat: add amazing feature'` +4. 推送分支：`git push origin feat/amazing-feature` +5. 提交 Pull Request -[待添加] +## 📋 路线图 + +- [ ] 完善 Ansible Playbook 调度与实时日志推送 +- [ ] 补充完整 API 接口文档 +- [ ] 添加单元测试与集成测试 +- [ ] 多集群跨集群操作支持 +- [ ] 操作回放与审计录像 + +## 📜 许可证 + +本项目采用 [Apache License 2.0](LICENSE) 开源协议。 + +--- + +
+ +**如果觉得有用，请点个 ⭐ Star 支持一下！** + +