小码农 猫的一生在打哈欠中度过
博客从 Java 迁到 FastAPI,我踩的 11 个坑

博客从 Java 迁到 FastAPI,我踩的 11 个坑

前言

博客原来使用 OneBlog,Java 编写,Spring Boot + FreeMarker,在此基础上做过一些修改。服务器内存较小,运行负担较重,今年改用 FastAPI 重写。

重写过程由 AI 协助完成,需求由我提出,代码由 AI 编写。期间遇到若干问题,记录如下。

1. 手机登录后台返回 500

新站上线后,使用手机流量登录后台返回 500,改用家庭网络访问正常。

日志报错:

Data too long for column 'reg_ip'

数据库中 sys_user 表的 reg_ip、last_login_ip 字段为 varchar(30),从 Java 版本迁移而来。IPv6 地址最长为 45 字符,超出字段长度。

2408:8207:5a3b:2c10:9d3f:1e2a:8b7c:4f11

执行以下语句修改字段长度:

ALTER TABLE sys_user MODIFY reg_ip varchar(50), MODIFY last_login_ip varchar(50);

另外,代码中字段定义为 String(50),数据库中为 varchar(30),两者此前一直不一致。由于之前没有 IPv6 登录场景,该问题未暴露。

2. 备份脚本未生成备份文件

备份目录中没有生成文件,cron 任务配置正常,但执行未产生结果。

手动执行脚本,报错如下:

/bin/bash^M: bad interpreter: No such file or directory

开发机为 Windows,脚本文件行尾为 CRLF,Linux 下 bash 无法识别 \r 字符。

在 .gitattributes 中增加以下配置:

*.sh   text eol=lf
*.conf text eol=lf
*.py   text eol=lf
*.sql  text eol=lf

3. docker build 耗时过长

每次执行 docker build,在 Sending build context 阶段耗时约七八分钟。

项目中的 data/ 目录包含 MySQL 数据文件、上传图片、证书及日志,约 3.5G。Docker 在构建时会将整个目录打包发送至 daemon,无论镜像是否使用这些文件。

在 .dockerignore 中增加:

data/

4. nginx 升级后服务无法启动

nginx 由 1.18 升级至 1.30,启动时报错:

nginx: [emerg] "ssl" directive is deprecated, use the "listen ... ssl" directive instead

1.25.1 版本开始移除 ssl on; 写法,需调整配置:

# 原配置
listen 443;
ssl on;

# 调整为
listen 443 ssl;

共修改 6 个 vhost 文件。同时移除 TLSv1 和 3DES 相关 cipher 配置。

5. IPv6 无法访问

nginx 配置中已监听 [::]:80,DNS 中 AAAA 记录存在,但 IPv6 无法访问。

原因是 Docker 未启用 IPv6,桥接模式下端口映射不会生效,且没有报错信息。

调整为 network_mode: host 后访问正常。同时需删除 compose 文件中的端口映射配置:

# host 模式下不需要配置端口映射
ports:
  - "80:80"
  - "443:443"

networks、hostname 配置项在 host 模式下同样不可使用。

6. 阅读数未增长

文章页启用了缓存,缓存命中时直接返回 HTML,不执行业务逻辑。此前阅读数统计代码放在业务路由中,因此缓存命中时不会执行,导致阅读数没有变化。

统计代码需放在缓存逻辑外层,在请求进入缓存判断之前完成计数。

另外,文章页缓存 TTL 为 7 天。修改模板或配置后,需要重启服务清除缓存才能立即生效。

7. 自动摘要功能无效

后台的「自动生成摘要」功能此前一直可以返回结果,但生成的摘要是正文开头的截断内容:

所以新路径就是然后使用管理员打开cmd。\ProgramData\PackageCache创建的联接

原因是该功能调用腾讯云 NLP 接口,当前 SDK 中对应的类已不存在。调用时抛出异常,被 except Exception 捕获后返回空值,前端降级为截取正文前 120 字符。

因此此前生成的摘要并非接口输出,而是正文的直接截断。异常被静默处理后,功能表面正常,实际早已失效。

8. 发布时数据库连接被重置

更新 447 篇文章摘要时,生成了 151KB 的迁移 SQL。发布流程在数据库迁移步骤报:

ConnectionResetError: [Win32 10054] 远程主机强迫关闭了一个现有的连接

重试多次,均在同一位置中断。迁移脚本将 SQL 内容嵌入 SSH 命令发送,151KB 的载荷超出连接限制,服务端断开连接。

将文件拆分为 5 个 30KB 的文件后仍然失败,因为执行命令会将所有迁移文件的内容合并到同一条脚本中发送。

最终采用逐个执行迁移文件的方式:每个文件单独执行,全部完成后跳过发布脚本的迁移步骤,继续执行后续流程。

执行过程中查询确认,数据未被修改。

9. Redis 停用后阅读数重复计数

原站使用 Redis 对阅读数去重,同一 IP 访问同一文章 10 分钟内只计一次。

新站停用 Redis 后,去重信息改为在进程内保存。多 worker 模式下,各进程分别保存一份数据,同一访问会被重复计数。

因此当前只能使用单进程:

UVICORN_WORKERS: "1"

限流数据同样保存在进程内,如需启用多进程,这两部分需要改回 Redis。

10. cron 任务仍写入旧路径

服务器上的定时任务包含数据库备份、日志切分和证书同步,脚本中的路径为固定值:

BACKUP_DIR=/djc8/autojob/backup

项目目录调整后,网站服务正常,但 cron 任务仍向旧目录写入。由于旧目录仍然存在,执行未报错,问题未及时发现。

目前备份脚本已调整为导出、压缩、校验并保留 90 天。

11. 代码定义与数据库结构不一致

代码中字段定义为 String(50),生产数据库字段为 varchar(30),两者长期不一致,此前未引发问题。

原因是数据库结构从 Java 版本迁移而来,后续修改了代码定义但未同步数据库。

因此在修改表结构前,应先查询实际结构:

SELECT COLUMN_NAME, COLUMN_TYPE
FROM information_schema.COLUMNS
WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'sys_user';

最后

以上问题中,有多项属于执行失败但没有报错的情况:CRLF 脚本、漏配 .dockerignore、异常被捕获后返回空值、进程内去重、cron 固定路径。

这类问题排查难度较高,因为没有明确的错误提示,容易认为功能仍在正常运行。

改造已完成,站点目前运行正常。

赏
支付宝赞赏码
支付宝
微信赞赏码
微信
分享 微博 QQ 空间 豆瓣 Twitter

评 说

正在取来评说……

卷首