mirror of
https://github.com/lkddi/dell-fans-controller-docker.git
synced 2026-05-18 13:47:27 +08:00
完善开源发布配置和使用文档
This commit is contained in:
@@ -1,153 +1,176 @@
|
||||
# Dell风扇控制器
|
||||
# Dell Fans Controller / Dell 风扇控制器
|
||||
|
||||
## 项目简介
|
||||
Dockerized fan controller for Dell iDRAC/IPMI servers. It reads temperature sensors through `ipmitool` and adjusts fan speed automatically to reduce noise while keeping the server safe.
|
||||
|
||||
Dell风扇控制器是一个自动化工具，通过IPMI接口监控Dell服务器的温度并自动调节风扇转速。本项目基于原项目 joestar817/dell-fans-controller-docker 进行了大量改进和功能增强。
|
||||
通过 iDRAC/IPMI 自动读取 Dell 服务器温度，并根据温度调整风扇转速。适合希望降低噪音、但仍保留高温自动保护的家庭实验室、机房和 NAS 场景。
|
||||
|
||||
### 主要特性
|
||||
> Warning: manual fan control can cause overheating if configured incorrectly. Test with care and keep iDRAC automatic mode available as fallback.
|
||||
>
|
||||
> 警告：手动风扇控制配置不当可能导致过热。请先确认服务器散热状态，并保留 iDRAC 自动模式作为兜底。
|
||||
|
||||
- **精准温度监控**：通过IPMI接口获取服务器进出口、CPU等关键温度数据
|
||||
- **智能转速控制**：根据温度自动调节风扇转速，平衡散热效果和噪音
|
||||
- **网络容错能力**：具备强大的网络连接容错机制，能处理网络波动
|
||||
- **多架构支持**：支持 AMD64 和 ARM64 架构，兼容多种平台
|
||||
- **自动构建部署**：通过 GitHub Actions 自动构建和推送 Docker 镜像
|
||||
## Features / 功能
|
||||
|
||||
## 使用方法
|
||||
- Reads Dell iDRAC sensor data with IPMI LANPlus.
|
||||
- Automatically switches between manual fan speed and iDRAC automatic mode.
|
||||
- Reuses sensor data within one control cycle to reduce iDRAC session pressure.
|
||||
- Retries transient IPMI session failures and backs off after controller errors.
|
||||
- Supports Docker multi-arch images: `linux/amd64` and `linux/arm64`.
|
||||
|
||||
### 1. 准备工作
|
||||
- 通过 IPMI LANPlus 读取 Dell iDRAC 传感器数据。
|
||||
- 根据最高温度自动设置风扇转速，超过阈值时交还 iDRAC 自动控制。
|
||||
- 单次控制周期复用传感器数据，减少 iDRAC 会话压力。
|
||||
- 对临时 IPMI 会话失败进行重试，并在控制器异常后等待下一轮。
|
||||
- Docker 镜像支持 `linux/amd64` 和 `linux/arm64`。
|
||||
|
||||
在开始使用之前，请确保：
|
||||
## Quick Start / 快速开始
|
||||
|
||||
1. 登录iDRAC管理界面并启用IPMI服务
|
||||
2. 确保网络能够访问iDRAC管理接口
|
||||
3. 准备好iDRAC的用户名和密码
|
||||
Before running, enable IPMI over LAN in iDRAC and make sure the host running this container can reach the iDRAC management IP.
|
||||
|
||||
### 2. Docker运行
|
||||
运行前请先在 iDRAC 中启用 IPMI over LAN，并确认运行容器的主机可以访问 iDRAC 管理 IP。
|
||||
|
||||
### Docker
|
||||
|
||||
```bash
|
||||
# 基本运行命令
|
||||
docker run -d --name=dell-fans-controller \
|
||||
-e HOST=YOUR_IDRAC_IP \
|
||||
-e USERNAME=YOUR_USERNAME \
|
||||
-e PASSWORD=YOUR_PASSWORD \
|
||||
docker run -d --name dell-fans-controller \
|
||||
--restart always \
|
||||
lkddi/dell-fans-controller:latest
|
||||
```
|
||||
|
||||
### 3. 配置参数
|
||||
|
||||
| 环境变量 | 说明 | 默认值 |
|
||||
|---------|------|--------|
|
||||
| HOST | iDRAC管理接口IP地址 | 192.168.1.100 |
|
||||
| USERNAME | iDRAC用户名 | root |
|
||||
| PASSWORD | iDRAC密码 | your_idrac_password |
|
||||
|
||||
## 工作原理
|
||||
|
||||
### 温度控制策略
|
||||
|
||||
系统会监控服务器的多个温度传感器，取最高温度值作为控制依据：
|
||||
|
||||
| 温度范围(℃) | 风扇转速(%) | 说明 |
|
||||
|------------|------------|------|
|
||||
| 0-50 | 15 | 静音模式 |
|
||||
| 50-55 | 20 | 低速运行 |
|
||||
| 55-60 | 30 | 中速运行 |
|
||||
| 60-65 | 40 | 高速运行 |
|
||||
| >65 | 自动模式 | 由iDRAC自动调节 |
|
||||
|
||||
### 智能控制机制
|
||||
|
||||
- **模式切换**：系统在手动模式和自动模式间智能切换
|
||||
- **转速监测**：实时监测当前风扇转速，避免不必要的调整
|
||||
- **状态跟踪**：记录和跟踪风扇模式和转速设置历史
|
||||
|
||||
## Docker镜像
|
||||
|
||||
### 支持的架构
|
||||
|
||||
- AMD64 (x86_64)
|
||||
- ARM64 (aarch64)
|
||||
|
||||
### 镜像仓库
|
||||
|
||||
- Docker Hub: `lkddi/dell-fans-controller:latest`
|
||||
|
||||
### 自动构建
|
||||
|
||||
项目通过 GitHub Actions 实现了自动构建和部署：
|
||||
|
||||
- 每次推送代码到master分支时自动构建新镜像
|
||||
- 支持多架构镜像构建
|
||||
- 自动推送至Docker Hub和Harbor仓库
|
||||
|
||||
## 技术实现
|
||||
|
||||
### 核心功能
|
||||
|
||||
1. **精确的温度读取**：使用正则表达式解析IPMI传感器数据，准确提取温度值
|
||||
2. **RPM到百分比转换**：通过校准数据建立RPM与风扇转速百分比的准确转换关系（20% = 4800 RPM）
|
||||
3. **网络容错机制**：
|
||||
- 5次重试机制
|
||||
- 60秒超时设置
|
||||
- IPMI会话建立失败的特殊处理
|
||||
- 10秒重试间隔
|
||||
|
||||
### 配置选项
|
||||
|
||||
- 运行间隔：每60秒检查一次温度并调整风扇转速
|
||||
- 网络超时：60秒超时限制
|
||||
- 重试机制：5次失败后停止
|
||||
|
||||
## 部署示例
|
||||
|
||||
### Proxmox VE (PVE)
|
||||
|
||||
```bash
|
||||
docker run -d --name=dell-fans-controller \
|
||||
-e HOST=192.168.1.100 \
|
||||
-e USERNAME=root \
|
||||
-e PASSWORD=calvin \
|
||||
--restart always \
|
||||
-e PASSWORD=your_idrac_password \
|
||||
lkddi/dell-fans-controller:latest
|
||||
```
|
||||
|
||||
### 群晖NAS
|
||||
|
||||
在群晖的Docker应用中：
|
||||
|
||||
1. 搜索并下载 `lkddi/dell-fans-controller` 镜像
|
||||
2. 创建容器并设置环境变量
|
||||
3. 启用自动重启选项
|
||||
|
||||
## 安全说明
|
||||
|
||||
- 项目使用IPMI协议与服务器通信，需要相应的管理权限
|
||||
- 建议使用专用的IPMI管理账户
|
||||
- 定期更新镜像以获得安全补丁
|
||||
|
||||
## 故障排除
|
||||
|
||||
### 常见问题
|
||||
|
||||
1. **连接失败**：检查网络是否能访问iDRAC接口
|
||||
2. **认证失败**：确认用户名和密码正确
|
||||
3. **权限不足**：确保账户有IPMI控制权限
|
||||
|
||||
### 日志查看
|
||||
View logs / 查看日志：
|
||||
|
||||
```bash
|
||||
docker logs dell-fans-controller
|
||||
docker logs -f dell-fans-controller
|
||||
```
|
||||
|
||||
## 免责声明
|
||||
### Docker Compose
|
||||
|
||||
手动调整服务器风扇转速可能带来过热风险，使用本项目前请充分了解风险并做好数据备份。对于使用本项目引发的任何问题，作者概不负责。
|
||||
Copy the example environment file and edit the iDRAC settings:
|
||||
|
||||
## 贡献
|
||||
复制示例环境变量文件，并修改 iDRAC 配置：
|
||||
|
||||
欢迎提交 Issue 和 Pull Request 来改进项目。
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
## 许可证
|
||||
`.env` example / 示例：
|
||||
|
||||
该项目遵循原项目的开源协议。
|
||||
```env
|
||||
HOST=192.168.1.100
|
||||
USERNAME=root
|
||||
PASSWORD=your_idrac_password
|
||||
```
|
||||
|
||||
Start the service / 启动服务：
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
### Run with Python / 直接使用 Python 运行
|
||||
|
||||
Install dependencies / 安装依赖：
|
||||
|
||||
```bash
|
||||
# Debian / Ubuntu
|
||||
sudo apt update
|
||||
sudo apt install -y ipmitool python3
|
||||
|
||||
# macOS with Homebrew
|
||||
brew install ipmitool python
|
||||
```
|
||||
|
||||
Run / 运行：
|
||||
|
||||
```bash
|
||||
export HOST=192.168.1.100
|
||||
export USERNAME=root
|
||||
export PASSWORD=your_idrac_password
|
||||
python3 start.py
|
||||
```
|
||||
|
||||
## Configuration / 配置
|
||||
|
||||
| Variable | Required | Description |
|
||||
| --- | --- | --- |
|
||||
| `HOST` | Yes | iDRAC management IP address. / iDRAC 管理 IP。 |
|
||||
| `USERNAME` | Yes | iDRAC username with IPMI permission. / 有 IPMI 权限的 iDRAC 用户名。 |
|
||||
| `PASSWORD` | Yes | iDRAC password. / iDRAC 密码。 |
|
||||
|
||||
The application does not include default credentials. Missing variables will stop startup with a clear error.
|
||||
|
||||
程序不内置默认地址、账号或密码。缺少环境变量时会直接停止并输出明确错误。
|
||||
|
||||
## Temperature Policy / 温控策略
|
||||
|
||||
The controller reads all temperature sensors and uses the highest value.
|
||||
|
||||
控制器读取所有温度传感器，并使用最高温度作为控制依据。
|
||||
|
||||
| Temperature / 温度 | Fan Speed / 风扇转速 |
|
||||
| --- | --- |
|
||||
| `0-50 C` | `20%` |
|
||||
| `50-55 C` | `25%` |
|
||||
| `55-60 C` | `30%` |
|
||||
| `60-65 C` | `40%` |
|
||||
| `>65 C` | iDRAC automatic mode / iDRAC 自动模式 |
|
||||
|
||||
## Troubleshooting / 故障排查
|
||||
|
||||
Test IPMI manually first / 先手动测试 IPMI：
|
||||
|
||||
```bash
|
||||
ipmitool -H 192.168.1.100 -I lanplus -U root -P your_idrac_password mc info
|
||||
ipmitool -H 192.168.1.100 -I lanplus -U root -P your_idrac_password sdr
|
||||
```
|
||||
|
||||
Common issues / 常见问题：
|
||||
|
||||
- `Unable to establish IPMI v2 / RMCP+ session`: iDRAC IPMI service may be busy or unstable. Check network latency, duplicate monitoring scripts, and consider resetting iDRAC with `mc reset cold`.
|
||||
- Connection failed / 连接失败：确认容器主机能访问 iDRAC 管理 IP。
|
||||
- Authentication failed / 认证失败：确认用户名、密码和 IPMI 权限。
|
||||
- Permission denied / 权限不足：建议使用专用 iDRAC 用户，并授予 IPMI 控制权限。
|
||||
|
||||
## Release / 发布新版本
|
||||
|
||||
Docker images are published only from Git tags matching `v*`. Pull requests and `master` pushes only build and verify the image.
|
||||
|
||||
Docker 镜像只在推送 `v*` tag 时发布。PR 和 `master` 推送只做构建验证，不覆盖 `latest`。
|
||||
|
||||
```bash
|
||||
git tag v1.0.0
|
||||
git push origin v1.0.0
|
||||
```
|
||||
|
||||
The tag workflow publishes:
|
||||
|
||||
- `lkddi/dell-fans-controller:latest`
|
||||
- `lkddi/dell-fans-controller:v1.0.0`
|
||||
- `lkddi/dell-fans-controller:1.0.0`
|
||||
- `lkddi/dell-fans-controller:1.0`
|
||||
- `lkddi/dell-fans-controller:1`
|
||||
|
||||
GitHub Actions requires these repository secrets:
|
||||
|
||||
- `DOCKER_USER`: Docker Hub username.
|
||||
- `DOCKER_PASS`: Docker Hub access token. Do not use your account password.
|
||||
|
||||
## Development / 开发
|
||||
|
||||
Syntax check without generating tracked cache files:
|
||||
|
||||
```bash
|
||||
python3 -c "import ast, pathlib; [ast.parse(pathlib.Path(p).read_text(), filename=p) for p in ['start.py','controller/client.py','controller/ipmi.py']]"
|
||||
```
|
||||
|
||||
Build locally:
|
||||
|
||||
```bash
|
||||
docker build -t lkddi/dell-fans-controller:test .
|
||||
```
|
||||
|
||||
## License / 许可证
|
||||
|
||||
MIT
|
||||
|
||||
Reference in New Issue
Block a user