1. 从一个报错说起：这个异常到底在说什么
第一次看到zun.common.exception pymysql.err.DataError 1406, "Data too long for column 'exposed_ports' at row 1"这行日志的时候，很多人第一反应是“数据库字段长度不够，改大一点不就行了”。这个直觉方向没错，但如果你真的只是把字段从 varchar(255) 改成 text 就收工，后面大概率还会踩到第二个、第三个坑。因为这条报错背后牵扯的是 OpenStack Zun 项目在容器端口映射信息落库时的数据建模问题，涉及容器端口的数据结构、序列化方式、数据库字段类型选择，以及 Zun 内部对exposed_ports这个字段的处理逻辑。
先把结论摆在前面：这个报错的直接原因是 Zun 在向 MySQL 写入容器端口信息时，序列化后的字符串长度超过了exposed_ports列定义的最大长度，MySQL 在严格模式下直接拒绝写入并抛出 1406。但根因往往不是“端口太多”，而是端口数据的存储格式和你以为的不一样。
这篇文章适合三类人看：一是正在维护或二次开发 Zun 的工程师，二是被类似Data too long for column报错困扰的 OpenStack 运维，三是想理解“一个看似简单的字段长度问题为什么反复出现”的后端开发者。我会从数据流、字段设计、序列化格式、排查手段、修复方案几个层面把它讲透，并且给出可以直接复现和验证的操作步骤。
需要提前说明的是，下面涉及的代码路径、表结构、字段类型都是基于 Zun 常见版本的通用实践，不同版本之间可能有细微差异，具体以你手头的代码和数据库实际结构为准。我会在关键位置标注“以实际环境为准”，避免你照搬之后发现对不上。
2. 报错背后的数据流：exposed_ports 是怎么被写进数据库的
2.1 从容器创建请求到数据库写入的完整链路
要理解这个报错，得先搞清楚exposed_ports这个字段在 Zun 里是怎么流转的。用户通过 API 创建一个容器，请求体里可能带有端口映射信息，比如把容器内的 80 端口映射到宿主机的某个端口。这个信息在 API 层被解析后，会经过 Zun 的 conductor、compute 等组件，最终落到数据库的container表里，字段名就是exposed_ports。
关键点在于：API 层收到的端口信息可能是字典、列表或者嵌套结构，但数据库列是字符串类型。所以中间必然有一个序列化过程，把结构化数据转成字符串再存进去。如果序列化后的字符串长度超过了列定义的长度，MySQL 就会报 1406。
这里有个容易被忽略的细节：exposed_ports存的往往不是简单的端口号列表，而是包含了协议、容器端口、宿主机端口、IP 地址等信息的复合结构。比如一个端口映射可能长这样：{"80/tcp": [{"host_ip": "0.0.0.0", "host_port": 8080}]}。如果容器有多个端口映射，这个字符串会迅速膨胀。
2.2 为什么字段长度问题在 Zun 里特别容易触发
Zun 管理的是容器，容器的端口映射数量理论上可以很多。一个容器可以暴露几十个端口，每个端口又可能有多个映射规则。如果序列化格式不够紧凑，或者用了 JSON 这种带大量括号和引号的格式，字符串长度会增长得很快。
更麻烦的是，Zun 的数据库迁移脚本里，exposed_ports字段的初始定义可能只给了 255 个字符。这个长度在早期版本、端口映射简单的场景下够用，但随着使用场景复杂化，255 很快就不够了。而且 MySQL 在严格模式下（STRICT_TRANS_TABLES）不会自动截断，而是直接报错，这就导致容器创建失败。
我见过一个典型案例：某环境里一个容器映射了 12 个端口，每个端口有 host_ip、host_port、container_port、protocol 四个字段，序列化后字符串长度超过了 600 字符，而字段定义还是 varchar(255)，于是每次创建这个容器都失败，日志里就是这条 1406。
2.3 报错信息里的 row 1 意味着什么
at row 1这个提示经常让人困惑。它不是说“第一行数据有问题”，而是说 MySQL 在处理这条 INSERT 或 UPDATE 语句时，第一行（也就是当前这一行）就触发了错误。对于单行插入来说，row 1 就是你要插入的那条记录。所以看到 row 1 不用慌，它只是 MySQL 的固定表述，重点还是前面的Data too long for column 'exposed_ports'。
真正需要关注的是：这条 SQL 是谁发出来的，发出来的完整语句是什么，exposed_ports的实际值有多长。把这三点搞清楚，问题就解决了一半。
3. 字段类型与长度：varchar、text 到底该怎么选
3.1 varchar(255) 的由来与局限
很多 OpenStack 项目的数据库表里，字符串字段默认就是 varchar(255)。这个习惯来自早期 MySQL 的设计惯例：255 是一个字节能表示的最大值，索引效率高，存储开销小。对于大多数短字符串字段，比如 name、uuid、status，255 完全够用。
但exposed_ports不一样。它存的是序列化后的结构化数据，长度取决于端口数量和序列化格式。255 这个上限在端口映射稍多的情况下就会被突破。而且 varchar 在 MySQL 里是有行长度限制的，所有 varchar 字段加起来不能超过 65535 字节（实际还受字符集影响），所以也不能无脑把每个 varchar 都改得很大。
3.2 改成 text 是否一劳永逸
把exposed_ports从 varchar(255) 改成 text 是最直接的修复方式。text 类型最大可以存 65535 字节，对于端口映射信息来说通常足够了。但有几个注意点：
第一，text 字段不能有默认值，如果你的迁移脚本里给这个字段设了 default，改类型时会报错。第二，text 字段的索引行为和 varchar 不同，如果这个字段上有索引，需要评估影响。第三，改类型操作在大表上可能锁表，生产环境要选低峰期执行。
更重要的是，改字段类型只是治标。如果序列化格式本身很冗余，端口数量继续增长，text 也有被撑满的一天。所以更稳妥的做法是同时优化序列化格式，或者把端口信息拆到独立的关联表里。
3.3 字段类型选择对比
| 字段类型 | 最大长度 | 适用场景 | 注意事项 |
|---|---|---|---|
| varchar(255) | 255 字符 | 短字符串、uuid、名称 | 端口映射稍多就溢出 |
| varchar(1024) | 1024 字符 | 中等长度序列化数据 | 仍可能不够，且占行长度 |
| text | 65535 字节 | 长文本、JSON 序列化数据 | 不能设默认值，索引受限 |
| mediumtext | 16MB | 极长文本 | 一般用不到，性能开销大 |
| 独立关联表 | 无理论上限 | 结构化端口映射 | 需要改代码逻辑，改动大 |
从实操角度看，如果你的 Zun 环境端口映射数量可控（比如单容器不超过 20 个端口），改成 text 就够了。如果端口数量可能很大，或者你想彻底解决，那就需要考虑拆表。
4. 实操：定位、复现、修复这条报错
4.1 第一步：确认数据库当前字段定义
在动手改任何东西之前，先确认你环境里exposed_ports字段的实际定义。连上 Zun 使用的 MySQL 数据库，执行：
USE zun; SHOW CREATE TABLE container\G在输出里找到exposed_ports那一行，看看类型是 varchar 还是 text，长度是多少。同时确认 MySQL 的 sql_mode：
SELECT @@sql_mode;如果结果里包含STRICT_TRANS_TABLES，说明严格模式开启，超长会直接报错而不是截断。这个信息决定了你修复后的验证方式。
4.2 第二步：复现报错，拿到实际数据长度
想复现这个报错，最直接的方式是构造一个端口映射很多的容器创建请求。但更稳妥的做法是先查现有数据，看看已经存在的记录里exposed_ports最长有多长：
SELECT id, name, LENGTH(exposed_ports) AS len FROM container ORDER BY len DESC LIMIT 10;如果最长记录已经接近字段定义长度，那说明你的环境随时可能触发 1406。如果现有数据都很短，那触发报错的请求一定是端口映射特别多的那种。
要拿到触发报错的具体数据，可以临时打开 Zun 的 debug 日志，或者在 MySQL 的 general log 里找到那条失败的 INSERT 语句。把exposed_ports的值复制出来，用LENGTH()函数算一下实际长度，和字段定义对比，差距一目了然。
4.3 第三步：修改字段类型
确认问题后，修改字段类型。以改成 text 为例：
ALTER TABLE container MODIFY COLUMN exposed_ports TEXT;如果表数据量很大，建议用 pt-online-schema-change 或者 gh-ost 这类工具做在线变更，避免锁表影响业务。执行前务必备份表结构：
mysqldump -u root -p --no-data zun container > container_schema_backup.sql改完之后再查一次表结构，确认类型已经变成 text。
4.4 第四步：验证修复效果
修改完成后，重新发起之前失败的容器创建请求。如果创建成功，再查一下新记录的exposed_ports长度：
SELECT id, name, LENGTH(exposed_ports) AS len FROM container WHERE name = '你的容器名';确认数据完整写入，没有截断。同时检查 Zun 的 API 返回和容器实际端口映射是否一致，避免出现“数据库写进去了但业务逻辑不对”的情况。
注意：修改字段类型后，如果 Zun 代码里有对这个字段做长度校验的逻辑，也需要同步调整。否则可能出现数据库能存但代码层先报错的情况。
5. 比改字段更根本的：序列化格式与数据建模优化
5.1 当前序列化格式的冗余点
Zun 把端口映射序列化成字符串存储，常见格式是 JSON。JSON 的可读性好，但冗余也明显：每个键都要引号，每个层级都要括号，数字和字符串混在一起。一个包含 10 个端口映射的结构，JSON 序列化后可能有好几百字符，其中大量是格式符号。
如果换成更紧凑的格式，比如用分号分隔的键值对，或者用二进制序列化，长度可以大幅压缩。但这样做会牺牲可读性和兼容性，需要权衡。对于大多数环境来说，改字段类型加适度优化序列化格式就足够了。
5.2 拆表方案的利弊
把端口映射拆到独立的container_port表里，是更规范的做法。每个端口映射一行记录，字段包括 container_id、protocol、container_port、host_ip、host_port 等。这样就没有“字符串太长”的问题，查询和更新也更灵活。
但拆表的代价是代码改动大。Zun 里所有读写exposed_ports的地方都要改，数据库迁移脚本要写数据搬迁逻辑，API 返回格式可能也要调整。对于只是想让报错消失的场景，拆表属于过度设计。但如果你正在做 Zun 的深度定制，或者端口映射是核心业务数据，拆表值得考虑。
5.3 序列化格式优化的实操建议
如果你不想拆表，又想让字段长度更可控，可以优化序列化逻辑。比如在序列化前过滤掉默认值，host_ip 是 0.0.0.0 就不存，protocol 是 tcp 就省略。这样能显著减少字符串长度。
另一个技巧是用短键名。把container_port缩写成cp，host_port缩写成hp，虽然可读性差一点，但长度能省不少。不过这种做法会让日志和调试变困难，建议只在字段长度确实紧张时使用，并且做好注释。
6. 常见问题与排查技巧实录
6.1 改了字段类型还是报 1406 怎么办
这种情况通常有两个原因。一是改的不是 Zun 实际使用的数据库或表。OpenStack 环境里可能有多个数据库实例，Zun 配置里指定的连接地址才是真正生效的那个。检查/etc/zun/zun.conf里的[database] connection配置，确认你改的库和它一致。
二是字段改了但缓存没刷新。有些 ORM 框架会缓存表结构，改完数据库后需要重启 Zun 服务。先重启再试，如果还不行，检查代码里是否有硬编码的长度校验。
6.2 报错消失但数据被截断
如果 MySQL 没有开启严格模式，超长数据会被自动截断而不是报错。这种情况下报错消失了，但exposed_ports里存的是不完整的 JSON，后续解析会失败。所以修复后一定要验证数据完整性，不能只看“不报错了”。
检查方法：对比 API 返回的端口映射和数据库里存的内容，或者直接解析exposed_ports字段，看是否能正常反序列化。
6.3 多个字段同时报 Data too long
如果日志里不止exposed_ports一个字段报 1406，说明这个表的多个字符串字段都偏短。这时候不要一个个改，先梳理这个表所有 varchar 字段的实际使用情况，批量评估哪些需要扩容。但要注意 MySQL 的行长度限制，不能无限制地扩大所有 varchar。
6.4 常见问题速查表
| 现象 | 可能原因 | 排查方法 | 解决方式 |
|---|---|---|---|
| 改字段后仍报 1406 | 改错库或服务未重启 | 检查 zun.conf 连接配置，重启服务 | 改对库并重启 |
| 报错消失但数据不对 | 非严格模式截断 | 解析字段内容验证完整性 | 开启严格模式并扩容字段 |
| 多字段同时报错 | 表设计整体偏短 | 查表结构，统计各字段长度 | 批量评估扩容 |
| 只有特定容器报错 | 该容器端口映射特别多 | 查该容器请求体 | 扩容字段或优化序列化 |
| 迁移后新环境报错 | 迁移脚本字段定义旧 | 对比新旧环境表结构 | 同步更新迁移脚本 |
6.5 几个我踩过的坑
第一个坑是只改了主库没改从库。如果 Zun 配置了读写分离，写操作走主库，但表结构变更没有同步到从库，后续读操作可能出问题。改字段时要把所有相关实例都改到。
第二个坑是忽略了字符集。varchar 的长度单位是字符，但实际存储受字符集影响。utf8mb4 下，一个字符最多占 4 字节，varchar(255) 实际可能占用超过 255 字节。如果字段定义是按字节算的，换算时要小心。
第三个坑是改完字段没更新代码里的常量。有些项目会在代码里定义字段最大长度，用于前置校验。数据库改了但代码没改，会出现“数据库能存但代码不让过”的尴尬情况。
7. 从这条报错延伸出的数据库设计思考
Data too long for column这类报错，表面看是长度问题，深层看是数据建模时对“数据增长”预估不足。很多字段在设计初期只考虑了当前场景，没考虑未来数据量增长和格式变化。exposed_ports就是一个典型：早期 Zun 的端口映射简单，255 够用；后来场景复杂了，255 就不够了。
我在实际维护中总结出一个经验：对于存储序列化结构化数据的字段，不要用 varchar，直接用 text。因为序列化格式和数据结构都可能变化，长度很难预估。text 虽然有一些限制，但至少不会因为长度问题导致业务失败。如果性能敏感，可以在应用层做压缩后再存。
另一个经验是，数据库迁移脚本要定期回顾。OpenStack 项目的迁移脚本是累加的，新环境按顺序执行所有迁移。如果早期迁移里字段定义偏短，后期迁移又没有修正，新环境就会继承这个问题。定期检查迁移脚本的最终效果，比出了问题再改更省事。
最后再分享一个小技巧：在 Zun 的配置里可以临时开启 SQL 语句日志，把实际执行的 INSERT 语句完整记录下来。这样再遇到类似报错，直接看日志里的语句和参数，比猜来猜去快得多。具体配置在[database]段里调整connection参数，加上?charset=utf8mb4和日志相关选项，具体以你使用的 SQLAlchemy 版本为准。
这个问题的修复本身不复杂，复杂的是定位过程。希望这篇内容能帮你少走几个弯路，下次再看到 1406 的时候，能直接定位到字段、拿到数据、改对类型，十分钟搞定。
