CodeIgniter 2.1.0 升级到 2.1.1 完整指南：MIME 类型更新与 IPv6 地址支持

• 后端
• Web框架

本篇指南面向仍在使用 CodeIgniter 2.1.x 系列的开发者，系统讲解如何将项目从 2.1.0 安全升级到 2.1.1。2.1.1 是 CodeIgniter 2.x 生命周期中的一个重要维护版本，核心变化集中在三处：system框架目录的更新、config/mimes.php中 MIME 类型表的扩充、以及为 IPv6 地址支持而必须执行的数据库列扩容。读完本文，你将掌握完整的升级操作步骤、每条步骤背后的源码级原理，以及升级后如何验证结果。文中所有关键结论均以当前仓库中的官方升级文档、更新日志与源码实现为依据。

升级前的准备：让站点下线

在执行任何文件替换之前，官方文档明确要求先把站点下线：用一份静态的index.php替换现有的入口文件。这是为了保证升级过程中访问者不会看到半新半旧的异常页面，也避免在框架文件替换的间隙产生不可预期的运行时错误。

# 建议的操作顺序 1. 备份现有 index.php（例如复制为 index.php.bak） 2. 用静态维护页内容覆盖 index.php（返回 503 或简单提示语） 3. 完成下方全部升级步骤后，再恢复原 index.php

这一步骤虽然简单，却是整个升级流程中保证可用性的关键前提，切勿跳过。

第一步：整体替换 system 目录中的框架文件

升级的主体操作是：用 2.1.1 版本的所有文件，替换站点system文件夹下的全部文件和子目录。

从当前仓库的目录结构可以看到，system目录包含core/、database/、helpers/、language/、libraries/、fonts/等子目录，覆盖了框架的运行时核心、数据库驱动、辅助函数与语言包。升级时应对这些内容做整体覆盖。

文档在此处特别加了一条重要提示：

如果你在这些文件夹中开发过任何自定义文件，请务必先为它们制作副本。

也就是说，如果曾经直接改动过system目录内的类（例如覆盖过system/core/Controller.php或往system/helpers/里添加过自定义辅助函数），升级前必须先把这些自定义内容另存副本，再执行覆盖，升级完成后把自定义改动合并回新版本文件。推荐的做法是遵循 CI 官方惯例，将自定义代码迁移到application/core/、application/helpers/等应用目录中，避免对system的直接改动，从而让升级过程变成纯粹的“一键替换”。

第二步：替换 config/mimes.php，更新 MIME 类型表

2.1.1 对application/config/mimes.php进行了更新，扩充了更多用户常用的 MIME 类型。官方文档要求将新版文件复制到application/config/mimes.php，覆盖旧版本。

升级后文件的实际变化可以在当前仓库的application/config/mimes.php中看到。例如新版为 Office 2007+ 文档补充了多个候选 MIME 类型：

// application/config/mimes.php 'docx' => array( 'application/vnd.openxmlformats-officedocument.wordprocessingml.document', 'application/zip', 'application/msword', 'application/x-zip' ), 'xlsx' => array( 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet', 'application/zip', 'application/vnd.ms-excel', 'application/msword', 'application/x-zip' ),

这正是 2.1.1 更新日志中提到的两项核心修复与改进：

• 修复了对 docx、xlsx 文件的 MIME 识别支持（见changelog.rst的 General Changes 部分）；
• 进一步改进了文件上传库（File Uploading Library）的 MIME 类型检测，相关文档位于 user_guide_src/source/libraries/file_uploading.rst。

一个值得注意的细节是：docx与xlsx的取值都是数组而非单个字符串，这是因为同一扩展名在不同环境下可能被检测出多种 MIME 值（浏览器、服务器配置、finfo扩展等各有差异）。CodeIgniter 的上传库在_file_mime_type()的检测逻辑中会把这些候选值逐一与上传文件的真实类型比对，从而显著降低“合法文件被误判拒绝”的概率。如果你在自己的应用里通过上传功能接收 Office 文档，这一项升级能直接改善兼容性。

自定义 MIME 类型的合并建议

如果旧版mimes.php中曾添加过业务自定义的 MIME 映射，直接覆盖会丢失这些配置。升级时应：

1. 先备份旧版application/config/mimes.php；
2. 以新版文件为基底完成覆盖；
3. 将旧版中自定义的键值对合并回新文件（注意保留新版原有的数组结构）。

第三步：更新 IP 地址表结构，为 IPv6 做准备

本次升级为框架引入了IPv6 IP 地址支持。为了能存储 IPv6 地址，所有用于保存 IP 地址的数据库列必须从原来的容量扩充到45 个字符。官方文档以 CodeIgniter 自带的 session 表为例，给出了如下 SQL：

ALTER TABLE ci_sessions CHANGE ip_address ip_address varchar(45) default '0' NOT NULL

这里有两个要点需要理解：

• 为什么是 45 个字符？IPv6 地址的完整文本表示最长可达 39 个字符（8 组 4 位十六进制加 7 个冒号），加上可能的端口后缀与格式余量，官方统一按 45 字符规划列宽，可覆盖完整 IPv6 表示，而 IPv4 地址（最长 15 字符）在该列宽下同样完全兼容。
• 不只是 session 表：凡是应用内自己维护了ip_address字段的表（如访问日志、登录记录、评论者 IP 等），只要该列用于存放来自$this->input->ip_address()的返回值，都应执行类似的ALTER TABLE扩容，避免升级后 IPv6 用户数据被截断或写入失败。

源码视角：2.1.1 的 IPv6 支持是如何实现的

IPv6 支持并不仅限于数据库列宽调整，框架层面有完整的配套实现。在system/core/Input.php中，ip_address()方法负责确定并校验访问者 IP，其关键逻辑包括：

1. 默认取$_SERVER['REMOTE_ADDR']作为初始值；
2. 若在application/config/config.php中配置了proxy_ips，则依次检查HTTP_X_FORWARDED_FOR、HTTP_CLIENT_IP、HTTP_X_CLIENT_IP、HTTP_X_CLUSTER_CLIENT_IP等转发头，在确认来源 IP 是可信代理后，采用转发头中的真实客户端 IP；
3. 最终通过valid_ip()校验，若无效则回退为0.0.0.0。

valid_ip()方法（system/core/Input.php）则通过 PHP 的filter_var()配合FILTER_FLAG_IPV4/FILTER_FLAG_IPV6分别校验两种协议格式，传参'ipv4'或'ipv6'即可限定校验协议，不传则两种协议均合法。

proxy_ips配置项在 application/config/config.php 中默认值为空字符串，支持三种写法：

// 方式一：逗号分隔的字符串 $config['proxy_ips'] = '10.0.1.200,192.168.5.0/24'; // 方式二：数组 $config['proxy_ips'] = array('10.0.1.200', '192.168.5.0/24'); // 方式三：留空，表示不启用代理 IP 检测（默认） $config['proxy_ips'] = '';

从源码（system/core/Input.php）可以看到，配置为逗号分隔字符串时会在运行时被自动转换为数组；同时支持子网掩码形式（如192.168.5.0/24），源码中会将 IP 与掩码地址转换为二进制后按前缀长度逐位比对（system/core/Input.php），IPv4 与 IPv6 分别按%08b与%016b的位宽展开。如果你的站点部署在 Nginx、HAProxy、CDN 等反向代理之后，请务必正确配置proxy_ips，否则拿到的将始终是代理服务器地址而非真实客户端 IP。

表单验证规则同步升级

配合 IPv6 支持，表单验证库也新增了 IP 格式参数。在system/libraries/Form_validation.php中，valid_ip规则被定义为：

public function valid_ip($ip, $which = '') { return $this->CI->input->valid_ip($ip, $which); }

使用方式（在控制器中设置验证规则时）：

$this->form_validation->set_rules('ip', 'IP Address', 'required|valid_ip'); // IPv4 或 IPv6 均可 $this->form_validation->set_rules('ip6', 'IPv6', 'required|valid_ip[ipv6]'); // 仅接受 IPv6 $this->form_validation->set_rules('ip4', 'IPv4', 'required|valid_ip[ipv4]'); // 仅接受 IPv4

这与更新日志中“为表单验证库新增 IP 格式参数支持”的描述（见changelog.rst）完全对应，完整的验证规则参考文档位于 user_guide_src/source/libraries/form_validation.rst。

Session 表字段的实际用途

ci_sessions表中的ip_address字段并非摆设。在 system/libraries/Session/drivers/Session_database_driver.php 中，数据库会话驱动会使用ip_address列进行会话查询与写入：

$this->_db->where('ip_address', $_SERVER['REMOTE_ADDR']); // ... 'ip_address' => $_SERVER['REMOTE_ADDR'],

并且，当会话配置中启用了match_ip选项时（Session_database_driver.php），每次会话读取都会按 IP 精确匹配，以增强会话绑定安全性。这意味着：如果你使用数据库会话驱动，这一步的列扩容是强制性的，否则 IPv6 用户的会话将无法正常匹配和存储。

2.1.1 版本中值得关注的其他改进

根据仓库内更新日志的记录（该版本发布于 2012 年 6 月 12 日），除了上述升级三步曲涉及的内容，2.1.1 还包含若干对日常开发有实际影响的修复：

• 辅助函数改进：url_title()性能与输出质量得到提升，现在可以使用任意字符串作为单词分隔符，同时继续兼容'dash'与'underscore'两种传统分隔符（changelog.rst）；
• Bug 修复类（changelog.rst）：
  • 修复form_open()将$action与site_url()而非base_url()比较的问题；
  • 修复上传库_file_mime_type()在mime_content_type()返回FALSE时可能失败的问题；
  • 修复 Windows 路径下图像处理库创建新文件时路径被忽略的问题（#538）；
  • 修复启用数据库缓存时，因先查缓存后绑定变量导致缓存永远无法命中的问题；
  • 修复 CSRF cookie 值在写入输出前未加校验、存在代码注入风险的问题；
  • 修复 PDO 驱动无条件在连接串中加入dbname参数导致无法使用 SQLite 的问题（#726）；
  • 修复CI_DB_pdo_driver::num_rows()依赖PDOStatement::rowCount()导致 SELECT 查询返回值不正确的问题；
  • 修复CI_Image_lib::clear()未正确清除 width、height 属性的问题（#1059）。

这些修复说明 2.1.1 并非简单的补丁叠加，而是对文件上传、表单、数据库层（尤其是 PDO/SQLite 场景）、图像处理与安全防护（CSRF）等多个子系统的一次集中加固，进一步凸显了升级的必要性。

升级完成后的验证与回滚

完成上述三步后，建议按以下顺序验证升级是否成功：

1. 恢复入口文件：将备份的index.php恢复，移除静态维护页；
2. 功能冒烟测试：重点验证文件上传（docx/xlsx 等 Office 文档）、IP 获取（$this->input->ip_address()）与登录会话三项功能；
3. IPv6 联调：如环境允许，用 IPv6 网络（或配置代理）发起一次请求，确认 session 表能正常写入 45 字符宽度的 IPv6 地址，且valid_ip规则能正确放行 IPv6 格式；
4. 数据库检查：确认所有自定义表中与 IP 相关的列均已扩容为varchar(45)。

若升级过程中发现问题需要回退，只需反向操作：恢复备份的system目录、恢复旧的application/config/mimes.php，并将ALTER TABLE的列宽改回原定义即可。由于本升级不涉及数据库表结构删除或数据迁移（仅列宽调整），回滚成本很低。

总结

从 2.1.0 升级到 2.1.1 是一个标准的小版本维护升级，官方文档给出了清晰的三步流程：整体替换system目录 → 更新config/mimes.php→ 扩容 IP 地址列以支持 IPv6。结合当前仓库源码可以看到，每一步背后都有扎实的实现支撑：MIME 类型数组化匹配提升了上传兼容性，Input库的valid_ip()/proxy_ips机制与表单验证的valid_ip[ipv4|ipv6]规则共同构成了完整的 IPv6 支持体系，而数据库会话驱动对ip_address列的使用则解释了为何列扩容是硬性要求。按本文步骤操作并完成验证，即可平滑完成本次升级。

• 后端
• Web框架