博客从 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 固定路径。
这类问题排查难度较高,因为没有明确的错误提示,容易认为功能仍在正常运行。
改造已完成,站点目前运行正常。
本文来自:博客从 Java 迁到 FastAPI,我踩的 11 个坑-小码农,转载请保留本条链接,感谢!
- 本文标签: java 迁移 python
- 本文链接: https://djc8.cn/archives/java-to-fastapi-11-pitfalls.html
- 版权声明: 本文由小码农原创发布,转载请遵循《署名-非商业性使用-相同方式共享 4.0 国际 (CC BY-NC-SA 4.0)》许可协议授权
