Linux | 空垠尘

Linux 运维实战排错与疑难杂症手册

Dukang Xu — Fri, 25 Sep 2026 16:00:00 +0800

引言：运维排错的系统性心智模型

在 Linux 与 macOS 的日常运维中，我们总会遇到一些让人措手不及的“灵异现象”：

磁盘明明显示还有几十 GB 空间，写入文件却提示 No space left on device；
服务端口被占用，却查不到任何监听进程；
容器或后端服务莫名其妙被系统静默杀死，没有任何业务日志；
高并发场景下突然爆发大量 Too many open files 导致雪崩。

排错不仅是敲几条命令，更是顺藤摸瓜的系统性推导过程。本文汇集一线运维中最高频的 6 类疑难杂症，给出可直接落地的排查逻辑与根治方案。

flowchart TD
    Issue["系统异常与服务报警"] --> A["1. 文件句柄耗尽
(Too Many Open Files)"]
    Issue --> B["2. 磁盘爆满/假满
(Inode 耗尽 / 句柄未释放)"]
    Issue --> C["3. 端口冲突与僵尸进程
(Address in use / Zombie)"]
    Issue --> D["4. 内存溢出被杀
(Kernel OOM Killer)"]
    Issue --> E["5. 时钟偏差与鉴权失效
(Clock Skew / NTP 同步)"]
    Issue --> F["6. macOS 环境网络阻塞
(Homebrew 源与网络排查)"]

一、彻底解决 `Too Many Open Files`（文件句柄耗尽）

在 Linux 与 macOS 哲学中，“一切皆文件”（包括 Socket 连接、管道、磁盘文件）。当并发连接数或打开的文件数超过系统预设限制时，就会抛出 Too many open files 错误。

1. Linux 生产环境彻底调优

仅在终端执行 ulimit -n 65535 只能在当前会话生效，重启即失效。需进行系统级固化：

① 修改系统级限制 (`/etc/security/limits.conf`)

1* soft nofile 655350
2* hard nofile 655350
3root soft nofile 655350
4root hard nofile 655350

② 修改 systemd 全局服务限制 (`/etc/systemd/system.conf`)

1[Manager]
2DefaultLimitNOFILE=655350
3DefaultLimitNPROC=655350

③ 查看当前进程占用的句柄数

1# 查看某个 PID 当前已打开的文件句柄数
2ls /proc//fd | wc -l

2. macOS 开发者环境调优

macOS 使用 launchd 管理系统参数，可通过以下方式调整：

1# 查看当前限制
2launchctl limit maxfiles
3
4# 临时增加限制 (当前终端有效)
5sudo launchctl limit maxfiles 65536 200000
6ulimit -n 65536

二、磁盘“假满”与 Inode 耗尽 (`No space left on device`)

当你尝试写入文件或保存配置时，系统报错 No space left on device，但执行 df -h 却发现磁盘还有大量剩余空间。此时通常有以下两种根源：

sequenceDiagram
    autonumber
    participant App as 应用程序 (如 Nginx / Java)
    participant Disk as 磁盘文件 (/var/log/app.log)
    participant Admin as 运维工程师

    App->>Disk: 持续写入大量日志 (持有文件句柄)
    Admin->>Disk: rm /var/log/app.log (删除了文件名)
    Note over Disk: 空间无法释放！因为 App 仍持有该句柄
    Admin->>App: 查找未释放句柄 (lsof | grep deleted) 并平滑重载
    Note over Disk: 磁盘空间瞬间恢复！

场景 A：文件已被 `rm` 删除，但进程仍持有句柄未释放

当你在程序运行期间删除了一个几百 GB 的日志文件，Linux 只会删除文件名（dentry），只要进程句柄未关闭，磁盘空间就绝不会被释放。

1# 1. 查找所有已被删除但仍被进程占用的文件
2sudo lsof | grep -i deleted
3
4# 2. 输出示例：
5# nginx   12345  www-data   4u   REG  8,1  53687091200  /var/log/nginx/access.log (deleted)
6
7# 3. 优雅释放空间（无需重启大应用）：清空该进程对应的文件描述符
8sudo truncate -s 0 /proc/12345/fd/4
9# 或者平滑重载服务：sudo systemctl reload nginx

场景 B：磁盘空间充足，但 Inode（索引节点）耗尽

大量微小文件（如海量缓存、小 session 文件、邮件队列）把 Inode 占满了：

1# 1. 检查 Inode 占用率
2df -i
3
4# 2. 逐级统计哪个目录下的小文件最多
5find /var/spool/ -type d -exec sh -c "echo -n '{}: '; ls -1 '{}' | wc -l" \; | sort -n -k 2

三、端口占用冲突与僵尸进程清理

1. 端口占用排查与一秒杀死

1# 1. 精准定位占用 8080 端口的进程与 PID
2sudo lsof -i :8080
3# 或
4sudo ss -tulnp | grep :8080
5
6# 2. 强力一键释放端口（自动杀死占用者）
7sudo fuser -k 8080/tcp

2. 僵尸进程（Zombie Process）定位与清理

僵尸进程在 ps aux 中状态标记为 Z（Defunct）。僵尸进程自身已经死亡，因此对它执行 kill -9 毫无作用，必须找到并重启/杀死它的父进程（PPID）：

1# 1. 查看系统中的所有僵尸进程
2ps aux | grep 'Z'
3
4# 2. 查找僵尸进程的父进程 PID
5ps -o ppid= -p 
6
7# 3. 优雅重启或终止父进程，让 init/systemd (PID 1) 回收僵尸
8sudo kill -HUP

四、进程静默被杀：Linux 内核 OOM Killer 排查

如果你的容器或程序莫名其妙闪退，且应用日志没有任何报错，十有八九是触发了 Linux 内核的 OOM Killer（内存耗尽保护机制）。

1# 1. 检查内核环形缓冲区中是否有 OOM 击杀记录
2sudo dmesg -T | grep -i -E "oom|out of memory|killed process"
3
4# 2. 输出示例：
5# [Fri Sep 25 14:30:22 2026] Out of memory: Killed process 28412 (java) total-vm:8388608kB, anon-rss:4194304kB

根治策略：

添加 Swap 交换分区（尤其适合 1G~2G 内存的轻量云主机与树莓派）：

1sudo fallocate -l 2G /swapfile
2sudo chmod 600 /swapfile
3sudo mkswap /swapfile
4sudo swapon /swapfile
5echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

在 Docker / Kubernetes 中设置合理的内存 Limit 与 Request。

五、系统时钟不同步导致 TLS/SSL 证书与鉴权失效

如果服务器系统时钟与标准时间偏差超过几分钟，会导致 HTTPS 证书校验失败、S3 对象存储签名拒绝、JWT Token 鉴权异常。

1# 1. 检查当前系统时间与 NTP 同步状态
2timedatectl status
3
4# 2. 确保时区设置为本地时区（如上海）
5sudo timedatectl set-timezone Asia/Shanghai
6
7# 3. 开启 NTP 自动时间同步
8sudo timedatectl set-ntp true

六、 macOS 开发环境 Homebrew 镜像加速与复原

国内访问官方 Homebrew 仓库缓慢时，可快速切换镜像源；出现同步异常时亦可随时复原：

 1# 1. 切换为清华大学 Homebrew 镜像源
 2export HOMEBREW_API_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles/api"
 3export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles"
 4export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git"
 5export HOMEBREW_CORE_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git"
 6
 7# 2. 恢复为官方默认源
 8unset HOMEBREW_API_DOMAIN
 9unset HOMEBREW_BOTTLE_DOMAIN
10export HOMEBREW_BREW_GIT_REMOTE="https://github.com/Homebrew/brew"
11export HOMEBREW_CORE_GIT_REMOTE="https://github.com/Homebrew/homebrew-core"
12brew update

结语

掌握底层机制与关键排错工具，能够让你在面对复杂故障时不再盲目重试，而是像外科手术一样精准定位问题并彻底解决。

Linux 与 DevOps 常用高频命令速查

Dukang Xu — Thu, 17 Sep 2026 10:00:00 +0800

引言：为什么我们需要一份现代化的命令速查手册？

Linux 命令行浩如烟海，许多开发者在日常运维和排查故障时，往往习惯机械性地复制粘贴，遇到复杂场景（如密钥管理、跳板机穿透、容器无 Shell 调试、定时任务静默失效）时容易陷入困境。

本文摒弃生搬硬套的语法手册风格，以 “真实生产与开发场景” 为导向，将分散的命令归纳为 5 大高频实战模块，助你建立清晰的命令行心智模型。

graph TD
    Root["现代 DevOps 命令体系"]
    
    Root --> A["1. SSH 远程与密钥矩阵"]
    A --> A1["Ed25519 现代高强密钥"]
    A --> A2["~/.ssh/config 多主机与跳板机"]
    A --> A3["本地与动态端口转发"]
    
    Root --> B["2. 定时任务与进程守护"]
    B --> B1["Crontab 语法与环境变量避坑"]
    B --> B2["Supervisord 进程崩溃自启"]
    
    Root --> C["3. 文件与系统管理"]
    C --> C1["ln 软硬链接管理与安全删除"]
    C --> C2["date 时区与时间戳转换"]
    C --> C3["磁盘与内存分析 (df / du / free)"]
    
    Root --> D["4. 网络排查与命名空间"]
    D --> D1["lsof 与 ss 端口连接定位"]
    D --> D2["nsenter 穿透容器命名空间"]
    
    Root --> E["5. 现代 CLI 生产力工具"]
    E --> E1["ripgrep 极速文本检索"]
    E --> E2["fzf 命令行交互模糊检索"]
    E --> E3["jq JSON 数据切片与提取"]

一、 SSH 远程连接与密钥矩阵

1. 生成现代安全的 SSH 密钥对（首选 Ed25519）

摒弃老旧且体积庞大的 RSA 2048/4096，优先使用性能更好、安全性更高的 Ed25519 椭圆曲线算法：

1# 生成 ed25519 密钥对（直接回车或设置保护密码）
2ssh-keygen -t ed25519 -C "your_email@example.com" -f ~/.ssh/id_ed25519
3
4# 一键分发公钥到远程服务器（免密登录）
5ssh-copy-id -i ~/.ssh/id_ed25519.pub user@192.168.1.100

2. 优雅管理多主机：配置 `~/.ssh/config`

无需每次记忆冗长的 IP、端口与用户名，在 ~/.ssh/config 中配置别名：

 1# 个人云服务器
 2Host cloud
 3    HostName 1.2.3.4
 4    User root
 5    Port 2222
 6    IdentityFile ~/.ssh/id_ed25519
 7
 8# 内网树莓派 / HomeLab
 9Host rpi
10    HostName 192.168.1.100
11    User pi
12    IdentityFile ~/.ssh/id_ed25519
13
14# 经由跳板机访问内网机器 (ProxyJump)
15Host internal-db
16    HostName 10.0.0.5
17    User dbadmin
18    ProxyJump cloud

配置后，只需输入 ssh cloud 或 ssh internal-db 即可直接一键直连！

3. SSH 端口转发神技

1# 本地端口转发 (-L)：将远程服务器的 3306 数据库映射到本地 13306
2ssh -N -L 13306:127.0.0.1:3306 user@remote-server
3
4# 动态 SOCKS5 代理 (-D)：把远程机器变成轻量 SOCKS5 代理通道
5ssh -N -D 10808 user@remote-server

二、定时任务与守护进程管理

1. Crontab 语法与关键避坑指南

Crontab 的标准时间格式为 5 段：分时日月周。

1# ┌───────────── 分钟 (0 - 59)
2# │ ┌─────────── 小时 (0 - 23)
3# │ │ ┌───────── 日 (1 - 31)
4# │ │ │ ┌─────── 月 (1 - 12)
5# │ │ │ │ ┌───── 星期几 (0 - 7, 0和7都代表周日)
6# * * * * * 命令

⚠️ Crontab 常见三大致命陷阱：
环境变量缺失：Crontab 默认的 PATH 非常简略（通常只有 /usr/bin:/bin），导致脚本找不到 docker 或 python3。务必使用绝对路径（如 /usr/local/bin/python3），或者在脚本开头显式声明 export PATH=$PATH:/usr/local/bin；

工作目录问题：Cron 执行时默认在用户家目录，相对路径会读错文件，脚本内请先 cd /path/to/workdir；
日志输出静默丢失：务必重定向标准输出与错误输出，便于复盘排错：
10 3 * * * /usr/bin/bash /opt/backup.sh >> /var/log/backup.log 2>&1

2. 使用 Supervisord 进行轻量级进程保活

对于非容器化的长驻进程（如 Python 爬虫、自建脚本），用 supervisord 能够轻松实现崩溃自启与日志管理：

1; /etc/supervisor/conf.d/my-app.conf
2[program:my-app]
3directory=/opt/my-app
4command=/usr/bin/python3 app.py
5autostart=true
6autorestart=true
7stderr_logfile=/var/log/my-app.err.log
8stdout_logfile=/var/log/my-app.out.log
9user=www-data

1# 常用管理命令
2sudo supervisorctl reread     # 读取新增配置
3sudo supervisorctl update     # 更新并启动新程序
4sudo supervisorctl status     # 查看所有进程状态
5sudo supervisorctl restart all # 重启所有受管进程

三、文件链接与系统时间操作

1. `ln` 软链接与硬链接实战

1# 创建软链接（符号链接）：ln -s <真实源文件/目录> <软链接名称>
2ln -s /mnt/data/music ~/Music
3
4# ⚠️ 注意事项：
5# 1. 建议源路径使用【绝对路径】，避免移动链接后路径断裂；
6# 2. 删除目录软链接时，严禁加末尾斜杠！
7rm ~/Music      # 正确：只删除软链接本身
8rm -rf ~/Music/ # 危险：可能会清空源目录下的真实内容！

2. `date` 时间格式化与时间戳互转

1# 1. 格式化输出当前标准时间
2date +"%Y-%m-%d %H:%M:%S"   # 输出: 2026-09-25 15:00:00
3
4# 2. 将 Unix 时间戳转换为人类可读时间
5date -d @1727258400 +"%Y-%m-%d %H:%M:%S"  # (Linux)
6date -r 1727258400 +"%Y-%m-%d %H:%M:%S"  # (macOS)
7
8# 3. 获取当前时间的 10 位 Unix 时间戳
9date +%s

四、容器与系统命名空间穿透 (`nsenter`)

在云原生和 Docker 运维中，许多精简镜像（如 Scratch、Distroless、Alpine 精简版）内部没有安装 bash、curl、netstat 等排错工具，导致 docker exec -it sh 无法进入。

此时，我们可以借助 Linux 内核原生工具 nsenter，直接从宿主机“穿透”进入容器的命名空间（Network/PID/Mount 等）：

sequenceDiagram
    autonumber
    participant Host as 宿主机 (拥有完整工具链)
    participant Kernel as Linux 内核命名空间
    participant Container as 极简容器 (无 curl/bash)

    Host->>Kernel: 查询容器主进程 PID (docker inspect)
    Host->>Kernel: nsenter -t  -n (共享容器网络命名空间)
    Kernel->>Container: 宿主机直接使用 tcpdump / curl 排查容器网络！

 1# 1. 获取容器在宿主机上的真实 PID
 2PID=$(docker inspect --format '{{ .State.Pid }}' )
 3
 4# 2. 仅穿透进入容器的网络命名空间 (Network Namespace)
 5# 这样可以直接在宿主机上使用宿主机的 curl/tcpdump/ss 测试容器内的网络情况！
 6sudo nsenter -t $PID -n ss -tulnp
 7sudo nsenter -t $PID -n tcpdump -i eth0 port 80
 8
 9# 3. 完整穿透进入容器全部命名空间
10sudo nsenter -t $PID -m -u -i -n -p

五、现代 CLI 生产力与效率工具集

用现代高性能开源工具替换传统老旧命令，体验呈数量级提升：

场景	传统命令	现代替代品	核心优势
代码/文本搜索	`grep -r`	`rg` (ripgrep)	基于 Rust，极速多线程，自动忽略 `.gitignore` 与二进制文件
交互式模糊搜索	纯命令翻页	`fzf`	交互式模糊检索历史命令、文件名、Git 提交
JSON 数据处理	手工解析	`jq`	命令行优雅过滤、高亮与切片提取 JSON 字段
磁盘空间排查	`du -sh *`	`ncdu` / `dust`	交互式目录占用分析，按大小可视化排序与删除
系统资源监控	`top`	`btop` / `htop`	炫酷仪表盘、支持 CPU/内存/网络/磁盘/进程树一览无余

 1# 常用效率一行流：
 2# 1. 查找包含某个关键词的文件
 3rg "DATABASE_URL" /opt/projects/
 4
 5# 2. 交互式模糊搜索历史执行过的命令
 6history | fzf
 7
 8# 3. 快速查找占用磁盘最大的前 10 个目录
 9du -ah /var/log | sort -rh | head -n 10
10
11# 4. 快速定位某个端口被谁占用并查看进程名
12sudo lsof -i :8080
13# 或
14sudo ss -tulnp | grep :8080

结语

熟练掌握现代命令行工具与进阶技巧，不仅能让日常部署与开发效率倍增，更能让你在面对各种疑难杂症时游刃有余。建议将本手册收藏备用！

树莓派 HomeLab 搭建与调优实战

Dukang Xu — Sun, 13 Sep 2026 10:00:00 +0800

引言：为什么树莓派是绝佳的家庭微型服务器？

树莓派（Raspberry Pi）以其极低的功耗（待机仅 2~5W）、完全静音的运行体验以及丰富的 GPIO 扩展接口，成为了无数开发者与极客玩家构建 7×24 小时不间断运行的 HomeLab（家庭实验室/微型服务器） 的首选设备。

然而，在实际从零折腾树莓派的过程中，许多新手往往会踩不少坑：

缺少外接显示器与键盘，不知道如何进行无头启动（Headless Boot）；
软件下载极慢，镜像源配置繁琐；
外接移动硬盘或 SSD 重启后盘符变动或权限丢失；
散热不佳导致 CPU 高温降频，或者风扇常开噪音扰民。

本文将基于长期的运维与折腾实践，从 系统初始化、存储扩展、硬件温控 到 Docker 基础环境，为你提供一份条理清晰、开箱即用的全套实战指南。

flowchart TD
    A["1. 无头烧录与系统安装
(SSH & Wi-Fi 免屏幕配置)"] --> B["2. 系统源与基础环境优化
(APT 镜像加速 / 静态 IP)"]
    B --> C["3. 存储扩容与硬盘挂载
(UUID / fstab / 权限固化)"]
    C --> D["4. 硬件散热与 GPIO 温控
(PWM 调速 / 寿命保护)"]
    D --> E["5. 部署 Docker & HomeLab 服务
(Compose / 容器矩阵)"]

一、系统烧录与无头初始化（无需显示器与键盘）

1. 烧录官方系统 (Raspberry Pi OS / Ubuntu Server)

推荐使用官方的 Raspberry Pi Imager 烧录工具：

操作系统选择：推荐 64 位无桌面版 Raspberry Pi OS Lite (64-bit) 或 Ubuntu Server 64-bit，资源占用极小，内存占用仅 100MB 左右；
高级预设配置（关键技巧）：在烧录器中点击右下角齿轮或按下 Ctrl + Shift + X（Mac: Cmd + Shift + X）唤出高级设置：
- 勾选 Set hostname（例如 rpi-server）；
- 勾选 Enable SSH，并设置账号密码或注入你的 SSH 公钥；
- 勾选 Configure wireless LAN（填写家中 Wi-Fi 名称与密码）；
- 设置时区为 Asia/Shanghai。
点击烧录到 TF 卡或 USB 固态硬盘中。

2. 首次启动与 SSH 远程连接

烧录完成后，将卡插入树莓派并接通电源。等待 1~2 分钟系统初始化，在电脑终端直接通过主机名或局域网 IP 连接：

1# 通过 mDNS 主机名直接连接
2ssh your_username@rpi-server.local
3
4# 或查询路由器后台获取分配的 IP 连接
5ssh your_username@192.168.1.100

二、系统源替换与基础网络调优

由于默认官方软件源位于海外，国内下载软件包可能极慢或超时。首次登录后建议立即更换为国内镜像源（以 Debian 12 Bookworm 为例）：

1. 备份并替换 APT 软件源

 1# 备份原源文件
 2sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak
 3sudo cp /etc/apt/sources.list.d/raspi.list /etc/apt/sources.list.d/raspi.list.bak
 4
 5# 替换系统主源为清华大学 / 阿里云镜像源
 6sudo sed -i 's|http://deb.debian.org/debian|https://mirrors.tuna.tsinghua.edu.cn/debian|g' /etc/apt/sources.list
 7sudo sed -i 's|http://security.debian.org/debian-security|https://mirrors.tuna.tsinghua.edu.cn/debian-security|g' /etc/apt/sources.list
 8
 9# 替换树莓派特有硬件驱动源
10sudo sed -i 's|http://archive.raspberrypi.org/debian|https://mirrors.tuna.tsinghua.edu.cn/raspberrypi|g' /etc/apt/sources.list.d/raspi.list
11
12# 更新缓存并升级基础软件
13sudo apt update && sudo apt upgrade -y

2. 安装常用基础运维工具

1sudo apt install -y curl wget git vim htop zsh tmux net-tools ufw

三、外接移动硬盘 / SSD 自动挂载与持久化

TF 卡的读写寿命和随机 I/O 性能有限，跑数据库和下载服务极易损坏。建议将外接移动硬盘或移动固态硬盘（SSD）挂载为数据存储盘。

sequenceDiagram
    autonumber
    participant USB as 外接硬盘 / SSD
    participant System as 树莓派系统内核
    participant Fstab as /etc/fstab 配置文件
    participant Mount as 挂载点 (/mnt/data)

    System->>USB: 读取设备唯一标识符 (UUID)
    Fstab->>System: 开机解析挂载规则 (nofail, UUID, ext4)
    System->>Mount: 自动挂载至指定目录并赋予权限

1. 查看硬盘设备与获取唯一 UUID

插入 USB 硬盘后，在终端执行：

1# 查看所有存储块设备
2lsblk -f

输出示例：

1NAME        FSTYPE FSVER LABEL  UUID                                 MOUNTPOINT
2sda
3└─sda1      ext4   1.0   DATA   e58f2371-d41a-4d7a-8b8a-927164b18210

⚠️ 注意：绝对不要使用 /dev/sda1 来挂载！如果下次重启插了其它 U 盘，盘符可能会变成 /dev/sdb1 导致启动卡死。必须使用 UUID。

2. 创建挂载点与配置 `/etc/fstab`

1# 1. 创建挂载目标目录
2sudo mkdir -p /mnt/data
3
4# 2. 编辑 fstab 自动挂载配置
5sudo vim /etc/fstab

在文件末尾追加一行（以 ext4 格式为例）：

1#                                                
2UUID=e58f2371-d41a-4d7a-8b8a-927164b18210     /mnt/data       ext4    defaults,nofail,noatime 0       2

💡 参数解析：

defaults：使用默认读写权限；

nofail：关键配置！即使硬盘未插上或识别失败，系统也不会卡死在启动自检流程；

noatime：关闭每次读取文件更新访问时间戳，减少写操作，延长磁盘与闪存寿命。

3. 测试挂载与权限设置

1# 测试配置是否正确（不报错即为配置无误）
2sudo mount -a
3
4# 将挂载目录的归属权分配给当前普通用户
5sudo chown -R $USER:$USER /mnt/data

四、硬件散热与 GPIO 智能温控风扇

树莓派 4B / 5 在高负载下发热量较大。如果风扇一直全速运转，不仅噪音刺耳，还会加速风扇轴承磨损。我们可以使用一段轻量级 Python 脚本配合 GPIO 实现智能温控调速。

1. 硬件接线示意

风扇正极（红线） $\rightarrow$ 接 GPIO 5V（Pin 4）或 3.3V（Pin 1）
风扇负极（黑线） $\rightarrow$ 通过三极管（如 NPN S8050）连接 GPIO GND（Pin 6）
三极管控制基极 $\rightarrow$ 接 GPIO 14（Pin 8，TXD）

2. 智能温控守护脚本 (`temp_control.py`)

创建脚本文件 /usr/local/bin/temp_control.py：

 1#!/usr/bin/env python3
 2# -*- coding: utf-8 -*-
 3import time
 4import os
 5import RPi.GPIO as GPIO
 6
 7# 配置参数
 8FAN_PIN = 14          # 控制引脚 BCM 14
 9TEMP_HIGH = 55.0      # 超过 55 度开启风扇
10TEMP_LOW = 45.0       # 低于 45 度关闭风扇
11
12GPIO.setwarnings(False)
13GPIO.setmode(GPIO.BCM)
14GPIO.setup(FAN_PIN, GPIO.OUT, initial=GPIO.LOW)
15
16def get_cpu_temp():
17    """读取 CPU 当前核心温度"""
18    with open("/sys/class/thermal/thermal_zone0/temp", "r") as f:
19        temp = float(f.read()) / 1000.0
20    return temp
21
22try:
23    fan_state = False
24    while True:
25        temp = get_cpu_temp()
26        if temp >= TEMP_HIGH and not fan_state:
27            GPIO.output(FAN_PIN, GPIO.HIGH)
28            fan_state = True
29        elif temp <= TEMP_LOW and fan_state:
30            GPIO.output(FAN_PIN, GPIO.LOW)
31            fan_state = False
32        time.sleep(5)
33except KeyboardInterrupt:
34    GPIO.cleanup()

3. 注册为 systemd 开机自启服务

创建守护进程配置文件 /etc/systemd/system/fan-control.service：

 1[Unit]
 2Description=Raspberry Pi Smart Fan Temperature Control
 3After=multi-user.target
 4
 5[Service]
 6Type=simple
 7ExecStart=/usr/bin/python3 /usr/local/bin/temp_control.py
 8Restart=always
 9RestartSec=10
10
11[Install]
12WantedBy=multi-user.target

1# 启用并启动温控服务
2sudo systemctl daemon-reload
3sudo systemctl enable --now fan-control.service

五、安装 Docker 与现代 HomeLab 运行环境

有了稳定的存储与散热，最后一步是安装 Docker 容器矩阵，让树莓派能轻松部署无数现代化开源服务：

 1# 1. 官方脚本一键安装 Docker
 2curl -fsSL https://get.docker.com | bash -s docker --mirror Aliyun
 3
 4# 2. 将当前用户加入 docker 组（免 sudo 执行 docker）
 5sudo usermod -aG docker $USER
 6
 7# 3. 安装 Docker Compose 插件
 8sudo apt install -y docker-compose-plugin
 9
10# 4. 配置 Docker 镜像加速与日志上限轮转（防止把磁盘撑爆）
11sudo mkdir -p /etc/docker
12sudo tee /etc/docker/daemon.json <<-'EOF'
13{
14  "log-driver": "json-file",
15  "log-opts": {
16    "max-size": "20m",
17    "max-file": "3"
18  }
19}
20EOF
21
22sudo systemctl restart docker

总结与后续

通过以上 5 步，你的树莓派已经脱胎换骨，成为了一台功耗极低、散热安静、存储充裕、开箱即用的现代化家庭服务器。

在此基础之上，你可以轻松运行诸如：

媒体中心：Navidrome（私有音乐）、Jellyfin（私人影院）；
数据同步与备份：Vaultwarden（密码管理器）、iCloudPD（手机相册备份）；
自动化与监控：RSSHub、Caddy 反向代理网关。

Linux | 空垠尘

Linux 运维实战排错与疑难杂症手册

引言：运维排错的系统性心智模型

一、 彻底解决 Too Many Open Files（文件句柄耗尽）

1. Linux 生产环境彻底调优

① 修改系统级限制 (/etc/security/limits.conf)

② 修改 systemd 全局服务限制 (/etc/systemd/system.conf)