Python开发实战笔记：文件操作、迁移与运维避坑

一、写在前面：把“搬砖”搬成方法论

日常开发里，真正消耗时间的往往不是实现新功能，而是排查那些“看起来很小”的问题：一个文件模式选错导致日志被清空，一次模型改名导致数据表消失，一次磁盘告警却找不到大文件。这些问题单独看都不难，但散落在日常里，就容易反复踩、反复查。本文以一份开发工作日记为线索，把其中七类高频问题重新梳理成体系化的实践笔记：文件读写模式、项目接入版本管理、ORM模型迁移、磁盘“假占满”排查、SSH自动化、绘图库中文字体配置，以及标准库文件操作模块的用法。每一类都从现象出发，讲清楚机制，再给出可执行的检查清单。

二、文件读写模式：w+ 不是“读写增强版”

很多开发者对文件模式的记忆停留在“w+、a+、wb 这些用起来很顺手”，却没认真推敲过语义差异，直到某天日志被莫名清空才恍然大悟。

1. 模式速查

模式	可读	可写	打开时的关键行为
r	是	否	文件必须存在，读取位置在开头
r+	是	是	文件必须存在，不清空内容
w	否	是	文件不存在则创建；存在则立即清空
w+	是	是	行为同 w，且可读——打开即清空
a	否	是	不存在则创建；写入永远追加到末尾
a+	是	是	可读可追加；初始读取位置在文件末尾
x	否	是	独占创建：文件已存在则报错，可防误覆盖

在上述模式后组合 b（如 rb、wb、ab）即以二进制方式处理，读写对象是 bytes 而非 str。

2. 三个最容易踩的坑

• 坑一：w+ 打开即清空。 它不是“能读的 w”，而是“读之前先把文件删光”。如果日志场景的本意是持续追加记录，用 w+ 打开已有日志文件的那一刻，历史内容就没了。
• 坑二：a+ 直接读是空的。 在主流实现中，以追加+读模式打开后，读取位置在文件末尾，read() 返回空字符串；想读历史内容需要先 seek(0)。而无论指针在哪，写入永远追加到文件末尾，seek 只影响读、不影响写。
• 坑三：文本模式与二进制模式混用。 带 b 的模式处理字节流，不带 b 的处理字符串；跨模式读写会出现编码类错误。涉及图片、压缩包等非文本内容时，必须使用二进制模式。

3. 结合场景：按业务ID生成日志文件

需求很典型：给一个业务ID，生成以该ID命名的日志文件，不同ID的日志互不干扰。正确姿势是“追加模式 + 显式编码”：

import pathlib
import time
LOG_DIR = pathlib.Path("logs")
def write_biz_log(biz_id: str, message: str) -> None:
    """按业务ID落日志：不同ID写不同文件，互不干扰。"""
    LOG_DIR.mkdir(parents=True, exist_ok=True)
    path = LOG_DIR / f"{biz_id}.log"
    # 关键点：使用追加模式，反复打开不会清空历史内容
    with path.open("a", encoding="utf-8") as f:
        f.write(f"[{time.strftime('%Y-%m-%d %H:%M:%S')}] {message}\n")

一句话记忆：r 求存在，w 先清空，a 往后追；加 + 可读可写，加 b 变字节流。

三、已有项目接入版本管理：从“能跑的代码”到受控资产

常见困境：仓库里的老代码缺模块跑不起来，只能基于一份可运行的完整代码重新纳管。此时流程正确与否，直接决定历史能否平滑衔接。

1. 标准流程

1. 在代码托管平台创建空白仓库，注意不要勾选“自动初始化说明文件”等选项，避免远端先产生一条与本地产出无关的历史，给首次合并制造冲突。
2. 在项目根目录初始化本地仓库，并配置提交者信息。
3. 提交前先写好忽略规则，把不该入库的内容挡在门外。
4. 关联远端仓库地址；若远端已有历史，先执行一次拉取并允许合并两条独立历史，解决冲突后再推送；若确认远端内容已废弃，可在团队沟通后覆盖推送。
5. 首次提交作为纳管基线，提交信息写清楚“基于某可用版本重建”。

2. Python 项目忽略规则参考

__pycache__/
*.py[cod]
.venv/
venv/
*.log
logs/
本地配置文件（含密钥、内网地址等敏感信息）
IDE配置目录/

3. 两条经验

• 纳管前先做一次完整备份或打镜像，任何版本操作都不该拿“唯一一份能跑的代码”冒险。
• 忽略规则要在首次提交前确定，否则历史里会混入大量应被忽略的文件，后续清理成本很高。

四、ORM模型迁移：改个表名，数据表为什么“没了”

主流Web框架的ORM都提供迁移机制，抽象流程一致：

模型定义变更 → 生成迁移脚本（对模型与迁移记录做差异对比）→ 人工审查 → 执行迁移 → 写入迁移记录表

其中迁移记录表非常关键：框架依据它判断“哪些迁移已经执行过”。如果这张表的记录丢失或被手工改动，框架可能重放历史迁移，尝试重建已存在的表，或跳过本应执行的变更。

1. 高危场景：重命名被理解为“删旧建新”

如果只修改了模型对应的表名，而框架的自动对比没有把它识别为“重命名”，生成的迁移脚本就会是“删除旧表 + 创建新表”的组合。脚本一旦执行，旧表连同数据一起消失，新表是一张空表——这就是“改个表名，表没了”的真相。

2. 防御清单

• 生成迁移文件后不要直接执行，先人工审查差异，重点看有没有删表、删字段等不可逆操作。
• 重命名需求优先使用框架提供的“重命名”类迁移操作，让框架生成改表名语句，而不是删建组合。
• 若同时调整模型类名与表名，尽量放在同一次变更里，帮助框架识别为重命名。
• 执行迁移前备份数据库，先在预发环境演练。
• 迁移记录表仅通过框架工具维护；一旦发现记录与真实表结构不一致，应先核对实际结构，再决定补记录还是校正结构，切勿盲目重放迁移。

五、磁盘“假占满”：df 显示100%，du 却找不到大文件

现象：服务器上各类服务突然不可用，接口全部超时；登录后查看文件系统占用，根目录已使用100%，但按目录逐层统计，实际数据量远小于磁盘容量。

1. 三类常见原因

• 文件已删除，但仍被进程占用。 文件被删除后，只要还有进程持有它的句柄，文件系统就不会真正释放空间。这类文件不在任何目录里，目录统计自然找不到，但文件系统层面它们仍然占着空间。
• inode 耗尽。 空间没满但 inode 用光，同样表现为“写不进任何文件”。海量小文件（会话文件、缓存碎片、任务队列落盘）是典型来源。
• 挂载点遮蔽。 在某个目录挂载新磁盘前，该目录下已有旧数据；挂载后旧数据被“盖住”，目录统计看不到，但依然占用原文件系统空间。

2. 排查路径

1. df -h            # 文件系统级占用，先确认是真满还是假满
2. du -x -d 2 /     # 逐层统计（-x 避免跨文件系统），定位差异层
3. df 与 du 差异大   → 排查已删除仍被占用的文件：
   lsof +L1         # 列出链接数为0但仍打开的文件
   （也可扫描 /proc/*/fd 中标记为 deleted 的项）
4. df -i            # 检查 inode 是否耗尽
5. 检查可疑挂载点    # 必要时临时卸载，查看被遮蔽的数据

3. 处置与预防

• 对“已删除仍占用”的文件：重启持有句柄的进程即可释放；不便重启时，可通过 /proc 下对应进程的文件描述符把文件内容清空，先腾出空间。
• 对 inode 耗尽：定位小文件目录，按业务规则批量清理或归档。
• 预防层面：监控告警应同时覆盖磁盘空间与 inode 使用率；日志、临时文件配置轮转与过期清理。

六、SSH自动化：让脚本替你登录服务器

巡检、拉日志、批量执行命令，这类重复劳动适合交给脚本。使用支持SSH协议的第三方库时，注意通用骨架与几个关键细节：

# 伪代码：SSH 自动化执行的通用骨架
client = ssh_connect(host, port=22, username=user,
                     credential=key_or_password, timeout=10)  # 建立连接
try:
    _, out, err = client.run("df -h && df -i")   # 执行命令
    print(out.read().decode("utf-8"))            # 读取标准输出
    print(err.read().decode("utf-8"))            # 消费标准错误，防止缓冲区积压导致卡死
finally:
    client.close()                               # 确保任何路径下都释放连接

实践要点：

• 认证优先使用密钥，避免口令明文出现在配置或代码中；主机指纹校验策略要显式声明，而不是默认全部接受。
• 每次执行都设置超时，并配合有限次重试；远端命令输出很大时，先落盘再取回，避免一次性读入内存。
• 读取结果时，标准输出与标准错误都要消费，否则缓冲区写满可能造成双方互相等待。
• 文件传输走库自带的SFTP能力，大文件分块传输并做完整性校验。
• 需要并发操作多台机器时，控制并发上限、复用连接，并记录每次操作的主机、命令与退出码，便于审计。

七、绘图库中文字体报错：从“字体不存在”说起

现象：在代码里指定了某种中文字体后，绘图库持续告警，提示该字体家族不存在并回退到默认西文字体，图中的中文显示为方块。

1. 原因分析

• 开发机通常装有中文字体，而服务器、容器往往是最小化环境，根本没有安装任何中文字体；
• 即使安装了字体，绘图库也可能依赖自维护的字体缓存，缓存未更新时同样找不到新字体；
• 代码中写的字体名必须与字体内部名称完全一致，写别名或错别字也会触发告警。

2. 解决思路

1. 把字体文件随项目一起分发，纳入版本管理或制品包，避免依赖目标环境“碰巧装了什么”。
2. 在代码中显式注册字体文件，并将其设置为默认字体，而不是只写一个字体名字符串。
3. 安装或更新字体后重建字体缓存。
4. 把“安装字体”写进环境构建脚本或镜像定义，保证开发、测试、生产环境行为一致。

# 伪代码：显式注册随项目分发的字体
font_manager.register("fonts/chinese_regular.ttf")   # 注册字体文件
plot_config.set("font.family", "该字体的内部名称")     # 指定为默认字体

具体API以所用绘图库文档为准，但“随项目分发字体 + 显式注册 + 环境构建时装字体”这三步是通用的。

八、标准库文件操作模块：文件级“重活”交给它

标准库中的 os 模块偏底层，适合路径拆解、属性查询；而涉及“把整个目录搬走、复制并保留元数据、递归删除”这类文件级操作，专用的文件操作模块更合适，也更少踩坑。

import pathlib
import shutil
src = pathlib.Path("build/output")
dst = pathlib.Path("archive/output")
# 目录级复制：目标目录已存在时不报错（需要较新的Python版本支持该参数）
shutil.copytree(src, dst, dirs_exist_ok=True)
# 移动或重命名：文件与目录通吃，跨文件系统时自动退化为“复制+删除”
shutil.move(str(src), str(dst / "output"))
# 磁盘用量查询：巡检脚本里可以直接比对阈值
total, used, free = shutil.disk_usage("/")

使用提醒：

• 递归删除不可恢复，封装这类操作时务必加保护：校验目标路径前缀、拒绝空路径与根路径、必要时二次确认。
• 复制文件时，若希望保留修改时间等元数据，选择带元数据版本的复制函数。
• 移动操作在跨文件系统时的语义是“复制后删除源”，大目录移动要评估耗时与中断风险。

九、结语：把日记沉淀为规范

回顾这几类问题，会发现每个“坑”背后都对应一块知识盲区：文件模式对应I/O语义，模型迁移对应框架的版本化机制，磁盘假满对应文件系统的空间回收原理，字体告警对应环境一致性，SSH自动化对应可靠的远程执行实践。建议把个人踩坑记录升级为团队资产：

• 建立检查清单：上线前审查迁移脚本、日志一律用追加模式、磁盘告警先看inode等；
• 高频问题沉淀为内部文档或脚手架，让后来者第一次就做对；
• 定期回顾日记，把“这次是怎么修的”改写成“以后该怎么防”。

搬砖不可避免，但搬得是否聪明，取决于每一次踩坑之后，有没有留下可复用的经验。