🔄 升级更新

ThinkAdmin 提供完善的升级更新机制，支持插件方式管理更新模块。

🚀 升级方式

Composer 插件模式

  • 管理方式: 通过 Composer 安装、更新 ThinkLibrary 及各业务插件
  • 服务注册: 插件通过 extra.think.services 注册 Service，由框架启动时自动加载
  • 模块更新: Admin、Wechat 等插件会按自身 Service 规则发布应用目录、静态资源、菜单和迁移
  • 命令辅助: ThinkLibrary 当前提供 xadmin:publish、xadmin:database、xadmin:package 等维护命令

升级提示

  • Composer 更新: 已有 composer.lock 的生产环境先使用 composer install --no-dev --optimize-autoloader；需要升级时再指定包名并使用 --with-all-dependencies，避免无计划地重算全部依赖
  • 迁移执行: 数据表结构以各插件 stc/database 迁移脚本为准，升级后按需执行迁移
  • 资源发布: 插件发布会覆盖受管理目录，已有定制内容时需要提前备份或本地化维护
  • 特殊情况: 特殊场景可下载代码替换指定目录，但仍应以插件 Service 和迁移脚本为准

开发总库与发布包

  • ThinkAdminDeveloper 是聚合开发总库，根 composer.json 通过 path 仓库引用 plugin/* 源码，并把 think-plugs-helper 作为开发依赖。
  • 普通项目应以 Packagist/Gitee/GitHub 发布包为准，不需要复制开发总库的 repositories 配置。
  • 修改通用能力时应修改对应源码包，例如核心服务改 think-library，后台模块改 think-plugs-admin，静态资源改 think-plugs-static。
  • 发布或升级后需要关注 vendor/services.php、vendor/versions.php、迁移脚本和受插件托管目录是否已重新生成。

⚙️ 升级步骤

1. 环境准备

  • PHP 版本: 先按 PHP 安全版本与维护建议 固定版本、SAPI 和扩展集合
  • Composer: 执行 composer validate --strict，确认 Composer 与 PHP 使用的是目标环境的实际二进制
  • 平台检查: 执行 composer check-platform-reqs，确认扩展 ABI 与依赖约束满足
  • 锁文件: 生产环境保留并审查 composer.lock，不要用删除锁文件的方式解决依赖冲突
  • 备份数据: 升级前备份数据库、配置、上传目录、运行时目录和当前发布包版本
  • 测试环境: 先在与生产相同的 PHP、SAPI、扩展和数据库版本中完成升级

2. 执行升级

  • 依赖安装: 生产发布使用 composer install --no-dev --prefer-dist --optimize-autoloader
  • 指定升级: 只更新目标组件，例如 composer update zoujingli/think-library --with-all-dependencies --optimize-autoloader
  • 插件安装: 安装相应的插件
  • 配置检查: 检查配置文件是否正确
  • 功能测试: 测试升级后的功能

3. 验证升级

  • 依赖验证: 执行 composer show --direct 和 composer check-platform-reqs，记录实际安装版本
  • 功能验证: 验证登录、权限、上传、Session、数据库事务、关键 API 和插件入口
  • 模式验证: 分别验证 CLI、FPM 与 Worker；同一主版本也不能用一种 SAPI 的结果替代其他模式
  • 性能测试: 观察响应时间、进程内存、FPM/Worker PID 和错误率
  • 数据检查: 确认迁移状态、数据完整性和回滚脚本可用
  • 日志查看: 检查 PHP、FPM、Web 服务器、Worker 和应用日志

🔐 PHP 安全升级

PHP 安全版本、EOL 分支和第三方回补包的判断以 PHP 安全版本与维护建议 为准。当前生产建议使用 PHP 8.4.27，最低安全基线为 PHP 8.2.35；PHP 8.3.36 和 8.5.12 需要先完成依赖、扩展和业务兼容性验证。

升级 PHP 引擎后必须分别验收 CLI、FPM 和常驻 Worker：

  1. 记录完整包版本、仓库来源、SAPI、扩展 ABI、签名或 SHA256，并确认三种运行方式使用的是同一安全包集合。
  2. 重启所有 FPM pool、队列进程和 Worker；应用层 reload 不能作为 PHP 二进制已升级的充分证据。
  3. 分别执行 Composer/迁移/定时任务、FPM HTTP 接口和 Worker 长驻请求回归。
  4. 保留升级前包版本、配置、Composer 锁文件、启动参数和进程 PID，发生兼容性问题时按记录回滚。

PHP 7.x 仍保留项目源码兼容目标，但官方没有本次两个问题的常规 7.x 安全发行版；PHP 7.4 只有官方最小源码回补分支。Remi 的 PHP 7.4 回补包和宝塔候选包必须按安全维护文档的证据要求独立核验，不能因为软件目录可下载安装就标记为已修复。

配置模板同步

环境变量中的数字默认以字符串返回，当前版本已在配置模板中显式转换以下字段：

字段默认值类型升级动作
SESSION_EXPIRE7200int核对现有 config/session.php
CACHE_REDIS_PORT6379int核对现有 config/cache.php
CACHE_REDIS_SELECT0int核对现有 config/cache.php

安装器不会覆盖已有配置文件。升级旧项目时应先备份配置，确认上述读取使用 (int)，再重启 FPM、CLI 常驻任务和 Worker。支持多端口的 MySQL hostport 保持字符串，不要套用整数转换。

按运行模式验收

  • FPM：通过受保护的诊断入口确认 PHP_VERSION、PHP_SAPI=fpm-fcgi 和扩展集合，重启全部 pool 后执行登录、上传、Session、数据库事务及异常恢复回归。
  • Worker：完整停止并启动 xadmin:worker，确认新 PID 和 CLI SAPI；按 ThinkPlugsWorker 生命周期说明 验证 Middleware 队列、Route 规则、超全局、Session、Cookie 和异常后恢复。
  • CLI/队列：检查 php、Composer、迁移、定时任务和队列监听器使用的实际二进制，不能用 FPM 或 Worker 结果代替。

项目级生命周期验收入口为 tests/check-lifecycle.php，推荐使用 bash tests/docker/run.sh 8.2 8.4 full 在隔离容器中运行。Worker 专项至少连续 100 次请求，使用 getGroup()->getRules() 判断规则数量稳定；PHP 官方 PHPT/CVE 回归另行记录。

🔧 PHP8 升级

兼容性支持

  • ThinkPHP 6/8: ThinkLibrary 当前声明兼容 topthink/framework 的 6.x 与 8.x 体系
  • 自动升级: 在 PHP8 环境按项目 composer.json 和 composer.lock 解析依赖；需要重新解析时使用 composer update --with-all-dependencies --optimize-autoloader
  • 标准开发: 按照 ThinkPHP 标准编写代码
  • 框架升级: 防止无法正常升级核心框架

配置调整

  • composer.json: 可能需要调整项目根目录的配置
  • 依赖组件: 部分依赖组件的配置规则不支持 PHP8
  • 版本建议: 提供建议修改的组件版本
  • 忽略配置: 项目中没有记录的可以忽略

⚠️ 重要提示

升级建议

  • 保留可发布模块: app/admin、app/wechat、public/static 等由插件发布的目录需要谨慎修改
  • 插件更新: 官方会不定时发布插件更新
  • 漏洞修补: 更新或修补系统漏洞
  • 个性化显示: admin 模块完全可以通过修改参数达到个性化显示

开发规范

  • 标准编写: 尽量按照 ThinkPHP 标准编写代码
  • 避免重构: 没必要重构来自定义显示内容
  • 参数修改: 通过修改参数来达到个性化显示

如何升级到 PHP8 ?

ThinkAdmin 已经支持在 PHP8 环境上运行。新安装或升级时应优先选择 PHP 安全维护文档中的安全版本，再根据当前 PHP 环境解析合适的依赖版本；PHP 版本升级本身不替代应用回归。 旧版本的系统升级可能需要调整项目根目录的 composer.json 配置，有部分依赖组件的配置规则不支持 PHP8，以下是建议修改的组件版本。 如果你的项目中没有记录，可以忽略该记录的配置；修改 composer.json 后应先在测试环境执行 composer update --with-all-dependencies --optimize-autoloader，审查锁文件差异并完成回归，再发布到生产环境。

{
  "require": {
    "php": ">=7.1",
    "ext-json": "*",
    "topthink/framework": "^6.0|^8.0",
    "topthink/think-view": "^1.0|^2.0",
    "zoujingli/ip2region": "^1.0|^2.0|@dev",
    "zoujingli/think-install": "^1.0|@dev",
    "zoujingli/think-library": "^6.1|@dev"
  }
}

可以通过执行 composer info 查看插件及组件版本，如果发现 topthink/framework 不是 8.x 版本，这时建议去检查本地是否为 PHP8 环境及依赖包中是否有不支持 PHP8 的依赖组件。 执行 php -v 可查看 PHP 版本信息，执行 composer -v 可查看 Composer 版本信息，执行 composer self-update 可升级 Composer 版本。

框架升级更新

安装 ThinkPlugsAdmin 插件模块的同时会安装 ThinkPlugsStatic 插件，将会强制更新替换 app/admin 目录和 public/static 的部分目录，在升级前一定要做好备份哦！具体说明可以跳转到对应插件查看。

PS. ThinkPlugsStatic 是 ThinkAdmin 专属后台样式脚本，由 ThinkAdmin 官方统一维护，个性化定制代码可以放置于 static/extra 目录，更新时不会替换该目录文件或目录。

# 升级 Composer（按组织变更窗口执行）
composer self-update

# 已有锁文件的项目按锁定版本安装
composer install --no-dev --prefer-dist --optimize-autoloader

# 需要升级插件时指定目标，并保留 composer.lock
composer require zoujingli/think-plugs-admin --with-all-dependencies --optimize-autoloader

不要删除 composer.lock 或直接清空 vendor 来绕过冲突。确需重新解析时，应在测试环境保留原锁文件副本，审查新的锁文件和依赖树，确认回归通过后再发布。

忽略更新替换

在目标目录下创建 ignore 文件（ 文件名没有后缀 ），该目录及子目录的文件将不会被替换更新，具体可以阅读对应插件或组件文档说明。

插件模块更新

部分应用插件更新会替换整个子应用的代码，不建议有修改过的模块更新，否则会覆盖丢失部分修改的内容。

# #### 在测试环境更新所有模块及组件
composer update --with-all-dependencies --optimize-autoloader

# #### 指定只更新 ThinkLibrary 组件
composer update zoujingli/think-library --profile --prefer-dist --optimize-autoloader

# #### 更新 ThinkAdmin 的系统模块 ThinkPlugsAdmin
composer update zoujingli/think-plugs-admin --profile --prefer-dist --optimize-autoloader

# #### 更新 ThinkAdmin 的微信模块 ThinkPlugsWechat
composer update zoujingli/think-plugs-wechat --profile --prefer-dist --optimize-autoloader

如果希望安装其他插件，可以跳转到 插件生态 查看详情。

最近更新:
Contributors: 邹景立, Anyon