# os-tools **Repository Path**: AIAgentOps/os-tools ## Basic Information - **Project Name**: os-tools - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-12-09 - **Last Updated**: 2026-02-05 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # os-tools ## 项目简介 os-tools 是一个企业级操作系统配置管理与部署平台，专为分布式集群环境设计。该平台提供统一的Web界面和API接口，用于管理服务器节点、部署配置文件、管理服务和版本控制。os-tools支持多种部署模式，包括全量配置部署和场景配置部署，能够满足复杂的企业级部署需求。 ## 目录 - [项目简介](#项目简介) - [功能特性](#功能特性) - [技术架构](#技术架构) - [目录结构](#目录结构) - [安装与部署](#安装与部署) - [配置说明](#配置说明) - [API接口文档](#api接口文档) - [使用说明](#使用说明) - [安全特性](#安全特性) - [开发与测试](#开发与测试) - [常见问题](#常见问题) - [维护与监控](#维护与监控) - [贡献指南](#贡献指南) - [许可证](#许可证) ## 功能特性 ### 配置管理 - **全量配置管理**：支持创建、编辑、删除全量配置 - **场景配置管理**：支持创建、编辑、删除场景配置 - **配置文件上传**：支持配置文件夹的上传和管理 - **配置元数据管理**：存储配置的名称、版本、模式、类型等信息 ### 部署管理 - **全量配置部署**：将全量配置部署到目标节点 - **场景配置部署**：将场景配置部署到目标节点 - **多节点批量部署**：支持同时向多个节点部署配置 - **部署历史记录**：详细记录每次部署的完整信息 - **部署状态跟踪**：实时跟踪部署进度和结果 ### 节点管理 - **节点信息管理**：管理目标节点的IP、端口、认证信息 - **节点状态监控**：实时监控节点的在线状态 - **SSH连接管理**：支持自定义SSH端口和认证方式 - **节点连接测试**：提供节点连接测试功能 ### 版本管理 - **版本创建与管理**：支持创建和管理不同版本的配置 - **版本部署记录**：记录每次版本部署的详细信息 - **部署状态跟踪**：跟踪每个节点的部署状态 ### 服务管理 - **服务基本信息管理**：管理服务的启动、停止命令等 - **服务节点关联**：将服务与节点进行关联管理 - **服务状态监控**：监控服务的运行状态 ## 技术架构 ### 后端技术栈 - **Python 3.8+**：主要开发语言 - **FastAPI**：高性能Web框架，支持异步处理 - **Pydantic**：数据验证和序列化 - **SQLAlchemy**：ORM框架，支持多种数据库 - **MySQL**：主要数据库 - **Paramiko**：SSH连接和文件传输 - **PyYAML**：YAML文件处理 - **Celery**：异步任务处理（可选） - **Redis**：任务队列和缓存（可选） ### 前端技术栈 - **Vue 3**：渐进式JavaScript框架 - **Vue Router 4**：路由管理 - **Pinia**：状态管理 - **Element Plus**：UI组件库 - **Vite**：构建工具 ### 部署架构 - **微服务架构**：模块化API端点 - **Docker容器化**：支持容器化部署 - **数据库连接池**：优化数据库连接性能 - **SSH连接管理**：连接复用和异常处理 - **文件上传处理**：临时文件管理和清理 ## 目录结构 ``` os-tools/ ├── tools-backend/ # 后端服务根目录 │ ├── config/ # 配置文件目录 │ │ ├── application.yaml # 应用配置 │ │ └── placeholder.yaml # 占位符配置 │ ├── scripts/ # 脚本目录 │ │ ├── deploy.sh # 部署脚本 │ │ ├── health_check.py # 健康检查脚本 │ │ └── init_db.py # 数据库初始化脚本 │ ├── src/ # 源代码目录 │ │ ├── app/ # 应用主目录 │ │ │ ├── api/ # API接口定义 │ │ │ │ └── v1/ # API v1版本 │ │ │ │ ├── configs.py # 配置管理API │ │ │ │ ├── nodes.py # 节点管理API │ │ │ │ ├── services.py # 服务管理API │ │ │ │ ├── versions.py # 版本管理API │ │ │ │ ├── files.py # 文件管理API │ │ │ │ ├── scenarios.py # 场景管理API │ │ │ │ └── deployments.py # 部署管理API │ │ │ ├── core/ # 核心配置 │ │ │ │ ├── config.py # 应用配置 │ │ │ │ ├── celery_config.py # Celery配置 │ │ │ │ └── log_config.py # 日志配置 │ │ │ ├── models/ # 数据模型 │ │ │ │ ├── config.py # 配置模型 │ │ │ │ ├── node.py # 节点模型 │ │ │ │ ├── service.py # 服务模型 │ │ │ │ └── deployment.py # 部署模型 │ │ │ ├── schemas/ # Pydantic模型/序列化 │ │ │ ├── services/ # 业务逻辑层 │ │ │ ├── repositories/ # 数据访问层 │ │ │ ├── utils/ # 工具模块 │ │ │ ├── shell/ # Shell脚本 │ │ │ └── static/ # 静态文件 │ │ │ └── uploads/ # 文件上传目录 │ │ └── main.py # 应用入口 │ ├── tests/ # 测试目录 │ ├── migrations/ # 数据库迁移 │ ├── requirements.txt # Python依赖 │ ├── Dockerfile # Docker构建文件 │ ├── docker-compose.yml # Docker Compose配置 │ ├── db_init.py # 数据库初始化脚本 │ ├── start_app.py # 应用启动脚本 │ └── README.md # 后端项目说明 ├── tools-frontend/ # 前端应用目录 │ ├── src/ # 源代码目录 │ │ ├── components/ # 可复用组件 │ │ │ ├── NavHeader.vue # 顶部导航 │ │ │ └── SideMenu.vue # 侧边栏菜单 │ │ ├── views/ # 页面组件 │ │ │ ├── Dashboard.vue # 仪表板 │ │ │ ├── Nodes.vue # 节点管理 │ │ │ ├── ConfigSettings.vue # 配置设置 │ │ │ ├── Files.vue # 文件管理 │ │ │ ├── Services.vue # 服务管理 │ │ │ ├── Version.vue # 版本管理 │ │ │ └── Settings.vue # 系统设置 │ │ ├── router/ # 路由配置 │ │ ├── stores/ # 状态管理 │ │ ├── api/ # API请求 │ │ └── main.js # 应用入口 │ ├── public/ # 静态资源 │ ├── package.json # 项目配置 │ ├── vite.config.js # 构建配置 │ └── README.md # 前端项目说明 ├── storage/ # 文件存储 │ ├── configs/ # 配置文件存储 │ └── versions/ # 版本文件存储 ├── README.md # 项目总览 ├── README.en.md # 英文版说明 └── .env.example # 环境变量示例 ``` ## 安装与部署 ### 环境要求 #### 系统要求 - **操作系统**: Linux/Unix 或 Windows (开发环境) - **Python**: 3.8 或更高版本 - **MySQL**: 5.7 或更高版本 - **Node.js**: 16 或更高版本 (前端开发) - **内存**: 至少 2GB RAM - **磁盘空间**: 至少 1GB 可用空间 ### 安装步骤 #### 1. 克隆项目 ```bash git clone cd os-tools ``` #### 2. 配置后端 ##### 2.1 安装Python依赖 ```bash cd tools-backend python -m venv venv source venv/bin/activate # Linux/Mac # 或 venv\Scripts\activate # Windows pip install -r requirements.txt ``` ##### 2.2 配置环境变量 ```bash cp .env.example .env # 编辑 .env 文件配置数据库连接信息 nano .env ``` ##### 2.3 数据库初始化 ```bash python db_init.py ``` ##### 2.4 启动后端服务 ```bash # 开发模式 python -m uvicorn src.main:app --host 0.0.0.0 --port 8000 --reload # 生产模式 gunicorn src.main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000 ``` #### 3. 配置前端 ##### 3.1 安装Node.js依赖 ```bash cd tools-frontend npm install ``` ##### 3.2 启动前端开发服务器 ```bash npm run dev ``` ##### 3.3 构建生产版本 ```bash npm run build ``` #### 4. Docker部署 (推荐) ##### 4.1 使用Docker Compose ```bash # 启动所有服务 docker-compose up -d # 查看服务状态 docker-compose ps # 查看日志 docker-compose logs -f ``` ##### 4.2 自定义环境变量 ```bash cp .env.example .env # 编辑 .env 文件以自定义配置 nano .env ``` ## 配置说明 ### 环境变量配置 #### 数据库配置 ```bash # 数据库连接配置 DB_HOST=localhost DB_PORT=3306 DB_USER=root DB_PASSWORD=your_password DB_NAME=os_tools DATABASE_URL=mysql+pymysql://root:your_password@localhost:3306/os_tools ``` #### Redis配置 (可选) ```bash # Redis连接配置 REDIS_HOST=localhost REDIS_PORT=6379 REDIS_PASSWORD= REDIS_DB=0 ``` #### 文件存储路径 ```bash # 配置文件存储路径 CONFIG_STORAGE_PATH=/data/configs SCENARIO_STORAGE_PATH=/data/scenarios VERSION_STORAGE_PATH=/data/versions ``` #### JWT配置 (可选) ```bash # JWT认证配置 JWT_SECRET_KEY=your_secret_key_here JWT_ALGORITHM=HS256 ACCESS_TOKEN_EXPIRE_MINUTES=30 ``` ### 配置文件说明 #### application.yaml 应用的主要配置文件，包含数据库连接、API配置等信息。 #### placeholder.yaml 占位符配置文件，定义了在部署过程中需要替换的变量。 ## API接口文档 ### 基础信息 - **基础URL**: `http://:/api/v1` - **认证方式**: JWT Token (可选) - **数据格式**: JSON ### 主要API端点 #### 配置管理 - `GET /configs` - 获取配置列表 - `POST /configs` - 创建新配置 - `GET /configs/{id}` - 获取特定配置 - `PUT /configs/{id}` - 更新配置 - `DELETE /configs/{id}` - 删除配置 #### 节点管理 - `GET /nodes` - 获取节点列表 - `POST /nodes` - 创建新节点 - `GET /nodes/{id}` - 获取特定节点 - `PUT /nodes/{id}` - 更新节点信息 - `DELETE /nodes/{id}` - 删除节点 #### 部署管理 - `POST /deployments` - 执行配置部署 - `GET /deployments/history` - 获取部署历史 - `GET /deployments/{id}/status` - 获取部署状态 #### 版本管理 - `GET /versions` - 获取版本列表 - `POST /versions` - 创建新版本 - `GET /versions/{id}` - 获取特定版本 - `PUT /versions/{id}` - 更新版本信息 ## 使用说明 ### 首次启动 1. 确保数据库已启动并配置正确 2. 运行数据库初始化脚本 3. 启动后端服务 4. 启动前端服务 5. 访问 `http://localhost:8080` (前端) 和 `http://localhost:8000/docs` (API文档) ### 创建第一个节点 1. 登录到管理界面 2. 进入"节点管理"页面 3. 点击"添加节点" 4. 输入节点信息（IP地址、SSH端口、用户名、密码等） 5. 点击"测试连接"确保连接正常 6. 点击"保存"完成节点添加 ### 部署配置 1. 进入"配置管理"页面 2. 选择要部署的配置类型（全量配置或场景配置） 3. 选择目标节点 4. 点击"部署"按钮 5. 监控部署进度和状态 ### 版本管理 1. 进入"版本管理"页面 2. 创建新版本或选择现有版本 3. 管理版本文件 4. 部署版本到目标节点 ## 安全特性 ### 认证与授权 - 支持基于JWT的用户认证 - 可配置的用户角色和权限 - API访问控制 ### 数据安全 - 配置文件加密存储 - SSH密钥管理 - 敏感信息保护 ### 网络安全 - 支持HTTPS - API请求限流 - 防止CSRF攻击 ## 开发与测试 ### 开发环境设置 1. 安装Python 3.8+ 和 Node.js 16+ 2. 克隆项目仓库 3. 按照安装步骤配置前后端 4. 设置开发环境变量 ### 测试 ```bash # 后端测试 cd tools-backend python -m pytest tests/ # 前端测试 cd tools-frontend npm run test ``` ### 代码规范 - Python代码遵循PEP 8规范 - JavaScript代码遵循ESLint配置 - 提交前运行代码格式化工具 ## 常见问题 ### 数据库连接问题 **问题**: 无法连接到数据库 **解决方案**: 1. 检查数据库服务是否运行 2. 确认环境变量中的数据库配置 3. 验证数据库用户权限 ### SSH连接失败 **问题**: 无法通过SSH连接到目标节点 **解决方案**: 1. 检查SSH服务是否在目标节点上运行 2. 验证SSH端口、用户名和密码 3. 确保网络连接正常 ### 部署失败 **问题**: 配置部署失败 **解决方案**: 1. 检查目标节点的磁盘空间 2. 验证SSH连接和权限 3. 查看部署日志以获取详细错误信息 ## 维护与监控 ### 日志管理 - 应用日志位于 `logs/` 目录 - 定期清理旧日志文件 - 监控错误日志以发现潜在问题 ### 数据库维护 - 定期备份数据库 - 监控数据库性能 - 清理过期数据 ### 系统监控 - 监控服务运行状态 - 监控系统资源使用情况 - 设置告警机制 ## 贡献指南 ### 代码贡献 1. Fork 项目 2. 创建功能分支 (`git checkout -b feature/AmazingFeature`) 3. 提交更改 (`git commit -m 'Add some AmazingFeature'`) 4. 推送到分支 (`git push origin feature/AmazingFeature`) 5. 创建 Pull Request ### 报告问题 - 使用 GitHub Issues 报告 bug - 提供详细的复现步骤 - 包含错误日志和环境信息 ### 提出建议 - 使用 GitHub Issues 提出功能建议 - 详细描述使用场景和预期功能 - 参与社区讨论 ## 许可证 本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件。 --- ## 支持与联系 如果您遇到问题或有建议，请通过以下方式联系我们： - 问题报告: [GitHub Issues](https://github.com/your-username/os-tools/issues) - 邮箱: your-email@example.com - 文档: [在线文档](https://example.com/docs) ## 致谢 - 感谢所有为项目做出贡献的开发者 - 感谢使用并支持 os-tools 的用户 - 感谢开源社区提供的优秀工具和框架