Fanap - CPU温度控制风扇程序

Fanap是一个用Go语言编写的Linux系统风扇控制程序，可以根据CPU温度自动调整风扇转速。支持直接运行和Docker容器化部署。

功能特性

✅ 自动检测CPU温度传感器和PWM风扇设备
✅ 根据温度线性调节风扇转速
✅ 支持自定义温度阈值和PWM范围
✅ 程序退出时自动恢复原始风扇控制模式
✅ 提供详细的调试信息
✅ 内置传感器检测工具（通过 -list 参数）
✅ 内置诊断工具（通过 -check 参数）
✅ Docker容器化支持
✅ 环境变量配置
✅ 支持多种控制模式（PWM、Cooling Device）
✅ GitHub Actions 自动构建和发布
✅ 预构建 Docker 镜像发布到 ghcr.io
✅ 版本化 Release 发布
✅ 支持systemd服务模式

系统要求

直接运行

Linux系统（Debian、Ubuntu、QNAP等）
内核支持hwmon硬件监控接口或thermal cooling device
需要root权限
CPU温度传感器和PWM风扇控制器

Docker运行

Docker 20.10 或更高版本
Linux主机（需要hwmon或thermal设备）
主机上的root权限或设备访问权限

快速开始

方式0: 使用预构建镜像（最快捷）

从 GitHub Container Registry 拉取镜像

# 拉取最新版本
docker pull ghcr.io/charleypeng/fanap:latest

# 拉取特定版本
docker pull ghcr.io/charleypeng/fanap:v1.0.3

运行容器

重要说明：程序需要 root 权限访问硬件设备（/sys/class/thermal 和 /sys/class/hwmon）。

docker run -d \
  --name fanap \
  --restart unless-stopped \
  --privileged \
  -e FANAP_VERBOSE=true \
  ghcr.io/charleypeng/fanap:latest

查看日志：

docker logs -f fanap

方式1: Docker快速启动（最简单，推荐）

1. 运行快速启动脚本

chmod +x docker-quick-start.sh
./docker-quick-start.sh

脚本会：

自动构建Docker镜像
让你选择配置模式
自动启动容器
提供管理命令

2. 查看日志

docker logs -f fanap

3. 管理容器

# 查看状态
docker ps | grep fanap

# 停止
docker stop fanap

# 重启
docker restart fanap

# 删除
docker rm fanap

方式2: Docker手动配置

1. 构建Docker镜像（可选，也可以使用预构建镜像）

./build-docker.sh

或直接使用预构建镜像：

docker pull ghcr.io/charleypeng/fanap:latest

2. 运行容器

推荐方式：使用特权模式

docker run -d \
  --name fanap \
  --privileged \
  -e FANAP_VERBOSE=true \
  ghcr.io/charleypeng/fanap:latest

注意：由于需要访问 /sys/class/thermal 和 /sys/class/hwmon 等硬件设备，容器必须以 root 用户运行并使用 --privileged 模式。

3. 查看日志

docker logs -f fanap

详细的Docker部署说明请查看 DOCKER.md

方式3: 直接运行（用于QNAP等）

1. 构建程序

在开发环境上构建Linux版本：

./build.sh

2. 上传到目标系统

scp build/fanap-linux-amd64 user@qnap:/tmp/

3. 在目标系统上运行

ssh user@qnap
cd /tmp
chmod +x fanap-linux-amd64
sudo ./fanap-linux-amd64 -verbose

详细的直接部署说明请继续阅读下面的章节。

命令行参数

基本命令

参数	说明
`-check`	检查hwmon设备（诊断模式）
`-list`	列出所有可用的温度传感器和PWM风扇设备
`-help`	显示帮助信息
`-version`	显示版本信息

风扇控制选项

参数	默认值	说明
`-interval`	5s	温度检查间隔
`-low-temp`	40.0	低温阈值（摄氏度），低于此温度使用最小PWM
`-high-temp`	75.0	高温阈值（摄氏度），高于此温度使用最大PWM
`-min-pwm`	50	最小PWM值（0-255）
`-max-pwm`	255	最大PWM值（0-255）
`-sensor`	auto	温度传感器路径（auto=自动检测）
`-pwm`	auto	PWM风扇设备路径（auto=自动检测）
`-verbose`	false	详细输出模式

环境变量（Docker）

所有配置都可以通过环境变量设置：

环境变量	默认值	说明
`FANAP_INTERVAL`	5s	温度检查间隔
`FANAP_LOW_TEMP`	40.0	低温阈值（摄氏度）
`FANAP_HIGH_TEMP`	75.0	高温阈值（摄氏度）
`FANAP_MIN_PWM`	50	最小PWM值（0-255）
`FANAP_MAX_PWM`	255	最大PWM值（0-255）
`FANAP_SENSOR`	auto	温度传感器路径
`FANAP_PWM`	auto	PWM风扇设备路径
`FANAP_VERBOSE`	false	详细日志输出

配置优先级

命令行参数 (最高优先级)
环境变量
默认值 (最低优先级)

使用示例

Docker运行

查看帮助信息

docker run --rm fanap:latest -help

查看版本信息

docker run --rm fanap:latest -version

诊断hwmon设备

docker run --rm \
  --privileged \
  fanap:latest -check

列出所有可用的传感器

docker run --rm \
  --privileged \
  fanap:latest -list

基本使用（自动检测）

docker run -d \
  --name fanap \
  --privileged \
  fanap:latest

自定义温度阈值

docker run -d \
  --name fanap \
  --privileged \
  -e FANAP_LOW_TEMP=35.0 \
  -e FANAP_HIGH_TEMP=65.0 \
  fanap:latest

快速响应模式

docker run -d \
  --name fanap \
  --privileged \
  -e FANAP_INTERVAL=2s \
  -e FANAP_MIN_PWM=100 \
  fanap:latest

静音模式

docker run -d \
  --name fanap \
  --privileged \
  -e FANAP_LOW_TEMP=50.0 \
  -e FANAP_HIGH_TEMP=80.0 \
  -e FANAP_MIN_PWM=30 \
  -e FANAP_MAX_PWM=200 \
  fanap:latest

使用docker-compose

# 修改docker-compose.yml中的环境变量后运行
docker-compose up -d

# 查看日志
docker-compose logs -f

直接运行

查看帮助信息

sudo ./fanap-linux-amd64 -help

查看版本信息

sudo ./fanap-linux-amd64 -version

诊断hwmon设备

sudo ./fanap-linux-amd64 -check

基本使用（自动检测）

sudo ./fanap-linux-amd64 -verbose

自定义温度阈值

sudo ./fanap-linux-amd64 -verbose -low-temp=45 -high-temp=80

快速响应模式

sudo ./fanap-linux-amd64 -verbose -interval=2s -min-pwm=100

静音模式（最低转速）

sudo ./fanap-linux-amd64 -verbose -low-temp=30 -high-temp=60 -min-pwm=30

指定传感器和风扇

sudo ./fanap-linux-amd64 -verbose \
  -sensor /sys/class/hwmon/hwmon0/temp1_input \
  -pwm /sys/class/hwmon/hwmon0/pwm1

工作原理

温度检测：定期读取CPU温度
PWM计算：
- 温度 ≤ 低温阈值：使用最小PWM
- 温度 ≥ 高温阈值：使用最大PWM
- 温度介于两者：线性插值计算PWM值
风扇控制：将计算出的PWM值写入PWM设备或Cooling Device
安全退出：程序退出时恢复原始风扇控制模式

支持的控制模式

PWM控制（标准Linux系统）

适用于大多数Linux系统
使用标准的 /sys/class/hwmon/hwmonX/pwmX 接口
支持0-255的PWM值范围

Cooling Device（QNAP等NAS设备）

适用于QNAP等使用thermal cooling device的设备
使用 /sys/class/thermal/cooling_deviceX 接口
自动将PWM值（0-255）映射到设备的冷却级别
支持开/关或多级控制

程序会自动检测并选择合适的控制模式。

故障排除

Docker运行

1. 容器无法启动

检查设备权限：

docker logs fanap
# 查看是否有权限错误

确保主机上的设备存在：

ls -la /sys/class/hwmon
ls -la /sys/class/thermal

使用特权模式（推荐）：

docker run -d \
  --name fanap \
  --privileged \
  fanap:latest

2. 容器启动但无法控制风扇

检查日志：

docker logs fanap

手动运行诊断：

docker run --rm \
  --privileged \
  fanap:latest -check

3. 权限错误

如果看到 permission denied 错误，确保使用 --privileged 模式：

docker run -d \
  --name fanap \
  --privileged \
  -e FANAP_VERBOSE=true \
  fanap:latest

重要：Docker 容器需要 root 权限才能写入 /sys/class/thermal/cooling_deviceX/cur_state。即使使用卷挂载和 --cap-add，某些系统仍可能限制访问。--privileged 模式是访问硬件设备的最可靠方式。

4. QNAP设备

QNAP使用thermal cooling device，使用特权模式：

docker run -d \
  --name fanap \
  --privileged \
  -e FANAP_VERBOSE=true \
  fanap:latest

QNAP 设备通常只有 2 级风扇控制（开/关），程序会自动适配。

直接运行

1. 找不到温度传感器或PWM风扇

诊断步骤：

首先运行诊断模式：

sudo ./fanap-linux-amd64 -check

常见原因和解决方案：

需要root权限
```
sudo ./fanap-linux-amd64 -check
```

内核模块未加载

# Intel CPU
sudo modprobe coretemp

# AMD CPU
sudo modprobe k10temp

hwmon目录不存在
- 检查BIOS设置，启用硬件监控
- 确保系统支持hwmon
温度传感器在其他位置
- 使用 -check 命令查看所有设备
- 手动指定传感器路径

2. QNAP设备

诊断：

sudo ./fanap-linux-amd64 -check

预期输出：

=== HWMon设备诊断 ===

设备: hwmon0
  名称: acpitz
  ✓ 温度1: /sys/devices/virtual/thermal/thermal_zone0/hwmon0/temp1_input ( [CPU]) [44.0°C]
  ✗ 未找到PWM风扇

设备: hwmon1
  名称: coretemp
  ✓ 温度1: /sys/devices/platform/coretemp.0/hwmon/hwmon1/temp1_input (Package id 0 [CPU]) [45.0°C]
  ...

设备: hwmon1
  ✓ 风扇: /sys/class/thermal/cooling_device4 ( [风扇]) [PWM=0]

如果只找到温度传感器但没有找到PWM风扇，这是QNAP正常现象。程序会使用cooling_device接口控制风扇。

推荐配置：

# 让风扇更早启动
sudo ./fanap-linux-amd64 -verbose -low-temp=35 -high-temp=60

温度和风扇建议

温度评估

对于NAS设备（QNAP TS-453D mini）：

✅ 优秀：< 50°C
✅ 良好：50-60°C
⚠️  偏高：60-75°C
❌ 危险：> 80°C

作为Systemd服务运行

1. 创建服务文件

复制 systemd/fanap.service 到系统目录：

sudo cp systemd/fanap.service /etc/systemd/system/

2. 修改服务参数（如需要）

编辑 /etc/systemd/system/fanap.service，修改 ExecStart 行的参数。

例如：

ExecStart=/usr/local/bin/fanap \
    -interval=5s \
    -low-temp=40 \
    -high-temp=75 \
    -min-pwm=50 \
    -max-pwm=255 \
    -sensor=auto \
    -pwm=auto \
    -verbose=false

3. 启动服务

sudo systemctl daemon-reload
sudo systemctl enable fanap
sudo systemctl start fanap

4. 查看状态

sudo systemctl status fanap

5. 查看日志

sudo journalctl -u fanap -f

6. 停止服务

sudo systemctl stop fanap

7. 禁用服务

sudo systemctl disable fanap

注意事项

⚠️ 此程序会修改风扇控制设置，使用前请了解风险
⚠️ 确保系统有足够的散热能力
⚠️ 建议先在 -verbose 模式下测试，确认程序工作正常
⚠️ 程序需要root权限或设备访问权限才能访问硬件监控接口
⚠️ Docker容器需要 --privileged 模式才能访问硬件设备
⚠️ 不同的主板和CPU支持的传感器和PWM设备不同
⚠️ 程序退出时会自动恢复原始风扇控制模式
⚠️ 如果遇到问题，先运行 -check 命令诊断
⚠️ QNAP等NAS设备使用特殊的cooling device接口，程序会自动适配
⚠️ 2级冷却设备（只有开/关）在温度阈值区间会间歇性工作，这是正常的

开发

构建本地版本（macOS）

make build
./build/fanap -help

构建Linux版本

make build-linux

构建Docker镜像

./build-docker.sh

创建版本标签并发布

# 创建并推送标签（会触发 GitHub Actions 自动构建和发布）
git tag v1.0.2
git push origin v1.0.2

创建标签后，GitHub Actions 会自动：

构建应用程序和 Docker 镜像
推送 Docker 镜像到 ghcr.io/charleypeng/fanap
上传构建产物到 GitHub Actions artifacts
如果是 Release，将产物附加到 Release 页面

拉取预构建镜像

# 从 GitHub Container Registry 拉取
docker pull ghcr.io/charleypeng/fanap:latest

# 拉取特定版本
docker pull ghcr.io/charleypeng/fanap:v1.0.2

格式化代码

make fmt

代码检查

make vet

运行测试

make test

清理构建文件

make clean

项目结构

fanap/
├── main.go                    # 主程序入口
├── go.mod                     # Go模块文件
├── Makefile                   # 构建脚本
├── build.sh                   # Linux交叉编译脚本
├── build-docker.sh            # Docker镜像构建脚本
├── docker-quick-start.sh      # Docker快速启动脚本
├── Dockerfile                 # Docker镜像定义
├── docker-compose.yml          # Docker Compose配置
├── README.md                  # 项目文档（本文件）
├── DOCKER.md                  # Docker部署详细文档
├── .gitignore                 # Git忽略文件
├── .dockerignore              # Docker构建忽略文件
├── systemd/
│   └── fanap.service          # Systemd服务配置
├── .github/
│   └── workflows/
│       └── docker-publish.yml # GitHub Actions 工作流
└── pkg/
    ├── temp/
    │   └── temp.go            # 温度传感器模块
    ├── fan/
    │   └── fan.go             # PWM风扇控制模块
    ├── thermal/
    │   └── thermal.go         # Thermal温度区域模块
    ├── cooling/
    │   └── cooling.go         # Cooling Device控制模块
    ├── controller/
    │   └── controller.go      # 控制器模块
    └── tools/
        └── hwmon.go           # 工具模块（传感器检测和诊断）

部署方式对比

方式	适用场景	优势	劣势
预构建镜像	通用Linux	无需构建、即用即跑	依赖 GitHub Container Registry
Docker快速启动	通用Linux	最简单、自动化、容器隔离	需要本地构建
Docker手动配置	通用Linux	灵活配置、环境变量管理	需要手动配置
直接运行	QNAP NAS	直接访问硬件、无容器开销	部署复杂、无容器隔离
Systemd服务	生产环境	自动启动、系统集成	配置相对复杂

自动发布和 CI/CD

GitHub Actions 工作流

项目使用 GitHub Actions 实现自动化构建和发布：

触发条件：
- 推送标签（如 v1.0.2）
- 推送到 main 分支
- 创建 GitHub Release
- 手动触发（workflow_dispatch）
自动执行的任务：
1. 检出代码
2. 设置 Go 环境
3. 构建应用程序（Linux x64）
4. 构建 Docker 镜像
5. 登录到 GitHub Container Registry
6. 推送 Docker 镜像到 ghcr.io/charleypeng/fanap
7. 上传构建产物到 Actions artifacts
8. 如果是 Release，将产物附加到 Release 页面

镜像标签策略

每次构建会生成以下标签：

latest - 最新的 main 分支构建
vX.Y.Z - 版本标签（如 v1.0.2）
<commit-sha> - 具体的提交哈希
<branch>-<sha> - 分支加提交哈希（PR 场景）

查看构建状态

访问 GitHub 仓库的 Actions 标签页查看所有工作流运行状态和日志。

下载构建产物

从 Release 页面下载（推荐）：
- 访问 Releases 页面
- 选择需要的版本
- 下载 fanap-linux-amd64 或 fanap-linux-amd64.tar.gz
从 Actions 页面下载：
- 访问 Actions 标签页
- 选择需要的工作流运行
- 在 Artifacts 部分下载构建产物

更新日志

v1.0.3 (2026-01-01)

修复 2 级冷却设备的级别映射问题（max_state=1 时的 PWM 映射）
对于只有开/关的设备，使用阈值逻辑（PWM > 127 开启，≤ 127 关闭）
优化日志输出，移除重复打印
添加详细的 2 级设备调试信息

v1.0.2 (2026-01-01)

修复 Docker 容器启动时的设备权限问题
更新所有 Docker 运行命令，使用 --cap-add SYS_RAWIO 和卷挂载替代 --device
添加 GitHub Actions 自动化工作流
支持自动构建和推送 Docker 镜像到 GitHub Container Registry (ghcr.io)
支持在 GitHub Release 中自动发布构建产物
添加 .github/workflows/docker-publish.yml 工作流
更新 docker-compose.yml 使用正确的卷挂载配置
更新所有文档中的 Docker 运行示例

v1.0.0 (2025-12-31)

初始版本发布
支持CPU温度传感器自动检测（hwmon和thermal_zone）
支持PWM风扇控制
支持Cooling Device风扇控制（QNAP等NAS）
支持自定义温度阈值和PWM范围
内置传感器检测工具（-list参数）
内置诊断工具（-check参数）
支持systemd服务模式
支持Docker容器化部署
支持环境变量配置
详细的帮助信息和错误提示
自动检测并选择最佳的控制模式

许可证

MIT License

贡献

欢迎提交Issue和Pull Request！

联系方式

如有问题或建议，请提交Issue。

Name		Name	Last commit message	Last commit date
Latest commit History 13 Commits
.github/workflows		.github/workflows
pkg		pkg
systemd		systemd
.dockerignore		.dockerignore
.gitignore		.gitignore
DOCKER.md		DOCKER.md
Dockerfile		Dockerfile
Makefile		Makefile
README.md		README.md
build-docker.sh		build-docker.sh
build.sh		build.sh
docker-compose.yml		docker-compose.yml
docker-quick-start.sh		docker-quick-start.sh
go.mod		go.mod
main.go		main.go
test-hwmon-structure.sh		test-hwmon-structure.sh

charleypeng/fanap

Folders and files

Latest commit

History

Repository files navigation

Fanap - CPU温度控制风扇程序

功能特性

系统要求

直接运行

Docker运行

快速开始

方式0: 使用预构建镜像（最快捷）

从 GitHub Container Registry 拉取镜像

运行容器

方式1: Docker快速启动（最简单，推荐）

1. 运行快速启动脚本

2. 查看日志

3. 管理容器

方式2: Docker手动配置

1. 构建Docker镜像（可选，也可以使用预构建镜像）

2. 运行容器

3. 查看日志

方式3: 直接运行（用于QNAP等）

1. 构建程序

2. 上传到目标系统

3. 在目标系统上运行

命令行参数

基本命令

风扇控制选项

环境变量（Docker）

配置优先级

使用示例

Docker运行

查看帮助信息

查看版本信息

诊断hwmon设备

列出所有可用的传感器

基本使用（自动检测）

自定义温度阈值

快速响应模式

静音模式

使用docker-compose

直接运行

查看帮助信息

查看版本信息

诊断hwmon设备

基本使用（自动检测）

自定义温度阈值

快速响应模式

静音模式（最低转速）

指定传感器和风扇

工作原理

支持的控制模式

PWM控制（标准Linux系统）

Cooling Device（QNAP等NAS设备）

故障排除

Docker运行

1. 容器无法启动

2. 容器启动但无法控制风扇

3. 权限错误

4. QNAP设备

直接运行

1. 找不到温度传感器或PWM风扇

2. QNAP设备

温度和风扇建议

温度评估

推荐配置

平衡模式（推荐）

激进散热模式

静音模式

作为Systemd服务运行

1. 创建服务文件

2. 修改服务参数（如需要）

3. 启动服务

4. 查看状态

5. 查看日志

6. 停止服务

7. 禁用服务

注意事项

开发

Packages