Installation and upgrade

安装与升级

本页用于通过 SandAdmin 的 SandPackage 安装、升级和卸载完整 SandIAM 包。先核对版本与兼容性及版本更新，下载从最新正式版开始。下方操作需要对应宿主权限、可恢复备份和与实际环境匹配的安装包。

前置条件

• 0.8.4 起声明 SandAdmin >=0.1.0（开放上限）；安装前核对所取包 info.ini 与插件仓库的实际宿主范围；最低声明不代表所有组合已验收；
• PostgreSQL 数据库和与该宿主匹配的 SandPackage。安装前核对锁定的 SandPackage 版本和候选包所需的安装能力；
• 可写的插件目录、匹配的 PHP 运行环境，以及管理端构建/部署能力；
• 完整 SandIAM ZIP、对应 Release 的 SHA-256 与来源记录；额外签名要求按发布包校验判断。

完整能力需要 PHP >=8.2，以及 ctype、curl、dom、json、ldap、libxml、 mbstring、openssl、PDO/pdo_pgsql、sodium、zip 和 zlib。这些分别承载身份字段校验、 HTTPS 对端、SAML、LDAPS、PostgreSQL、秘密加密和 SandPackage ZIP。安装前在解包目录运行：

php plugin/sand-iam/bin/check-runtime-requirements.php

自动化可追加 --json。失败表示当前 PHP 不能提供本发行版声明的完整能力；不要以关闭某个功能 来替代完整成品验收。命令只检查本机 PHP 能力，不连接数据库、不检查 schema，也不启动服务。

SandIAM 不负责创建数据库。请使用现有 SandAdmin 数据库；不要运行会隐式新建数据库的安装器或测试工具。

全新安装

1. 锁定 SandAdmin、SandPackage 和 SandIAM 版本，保存候选包摘要并记录宿主实际版本。

2. 按对应 Release 校验 ZIP 摘要与来源材料，确认根目录包含 info.ini、生命周期 SQL、plugin/sand-iam/、管理端、SDK、文档和许可证。

3. 备份数据库、插件文件、管理端产物和部署配置；验证备份可以读取。

4. 登录 SandAdmin 后进入“插件仓库”（菜单路由为 /plugin/sandpackage/install/index），上传完整 SandIAM ZIP；不要上传解开的子目录或只上传 plugin/sand-iam/。在安装候选详情中先阅读计划、版本和摘要，再选择“安装”。

5. 等待 SandPackage 的安装结果明确结束。若界面报告失败，停止在该阶段并保留候选摘要、阶段、错误码和恢复票据；不要改迁移账本、复制文件或手工导入 SQL。

6. 按配置参考从密钥系统注入基础密钥；可选功能和 worker 保持关闭， 直到对应迁移、对端与运行验收完成。启动或重载服务前，在插件目录运行 php plugin/sand-iam/bin/check-runtime-configuration.php --profile=release；预检失败时不要继续启动。

7. 发布管理端载荷：SandIAM 包内管理端源码的实际目录是 sandadmin-artd/src/views/plugin/sand-iam/。上传前可仅检查 ZIP 是否携带它：

   unzip -l "$SAND_IAM_ZIP" | rg 'sandadmin-artd/src/views/plugin/sand-iam/'

   本仓没有 SandAdmin 宿主的管理端构建或发布命令，不能据此虚构一条命令；使用宿主既定流程前先由 运维方确认其构建入口。仓内可运行的只读包内检查是 php sand-iam/tools/check-package-integrity.php，其 admin UI payload 通过只证明源码载荷关系完整。 前端构建入口由宿主提供，插件源码仓不代替宿主构建流程。 成功标志依次是 SandPackage 对完整 ZIP 明确报告安装成功、已部署管理端实际显示 SandIAM 菜单，并能打开 总览；任一缺失都不是“管理端已发布”。不要把源码目录存在当成页面已经发布。

8. 重新登录。确认左侧出现 SandIAM 菜单、能打开总览并在总览的“这次要完成什么？”选择当前目标；再打开应用用户入口 /app/sand-iam/account/，确认返回的是门户而不是 SandAdmin 后台登录页。

9. 创建一个隔离的演示范围，完成允许、拒绝、撤销、审计和清理。上述检查是安装后应执行的操作清单，不是所有目标宿主已完成真实安装的声明。

升级

1. 查阅根目录变更日志（对应版本包内 CHANGELOG.md），确认当前版本属于声明支持的升级路径；不要跨过未声明的中间版本。
2. 锁定升级前数据库结构、插件版本和包摘要，完成备份。
3. 在 SandAdmin“插件仓库”中上传完整升级 ZIP，在候选详情核对“当前版本 → 候选版本”、候选摘要和升级计划后，再选择升级。失败时保留错误阶段、候选摘要和恢复票据，不要手工标记成功。
4. 若 SandPackage 明确报告数据库阶段尚未开始或尚未提交当前候选的新迁移，只能由 SandPackage 以正常升级路径重试； 不要手工执行或重复导入 update.sql。
5. 若数据库阶段已提交，账本已有当前候选的新 revision，则 update.sql 不是可重复执行的幂等脚本；保留阶段、 错误和候选摘要，按 SandPackage 的“数据库已提交后”阶段恢复/完成流程处理，不得伪造 FAILED 或改账本。
6. 重新验证登录、授权、撤销、审计、worker 和外部协议，再开放业务流量。

当前正式版的升级前提

0.8.4 沿用 0.8.3 的标准升级，接受完整历史 43 条账本的 0.7.3 / 0.7.5 / 0.7.6 和旧 0.8.0 安装，以及已完成 043、拥有完整 44 条账本的 0.8.1 / 0.8.2 候选及 0.8.3 正式版。版本号本身不足以判断可升级，必须同时匹配每行账本和完整结构。

• 匹配旧 43 条来源：严格准入后，在同一事务执行原 043_scope_audit_event_key.pgsql，达到 44 条账本；失败一起回滚，不改写原审计事实。
• 匹配已完成 043 的 44 条来源：只校验完整结构与账本，升级载荷，不执行 DDL 或重放 043。
• 旧嵌入版 0.7.3 的 42 条账本不属于该标准来源，不能直接上传新包跨过缺失迁移，也不能手工补写账本。

已有 SandIAM 表时，不能选择全新安装覆盖数据。现有表接入须匹配目标包声明和迁移后结构；旧 43 条来源先走标准升级。无法确认来源时保留现场，交由维护者核对。公开 0.7.6-preview.2 的冻结 43 契约匹配，现场实际结构仍须核对。

早期 0.7.2 → 0.7.3 的 42 条终态是历史路径，详见升级版本参考，不是当前完整 43/44 来源的替代。

失败恢复

先回到 SandAdmin“插件仓库”中该候选的失败详情，保存阶段、候选摘要、错误码和 SandPackage 显示的下一步。

• 数据库阶段尚未提交：仅使用该候选提供的正常“重试”路径；不要手工执行或重复导入 update.sql。
• 数据库阶段已提交：先核对迁移账本是否已有当前候选的新 revision，再只按 SandPackage 显示的“数据库已提交后”恢复/完成路径处理。不要删除候选、伪造 FAILED 状态、改账本或用旧包覆盖文件。
• 无法判定阶段、没有可用的 SandPackage 恢复操作，或恢复操作报告失败：停止操作，保持备份和现场，向宿主/SandPackage 维护者提交版本、候选摘要、阶段、错误码、请求 ID 与脱敏日志。

0.7.3 正常包没有旧 0.6.0 → 0.7.0 recovery descriptor，不能借用历史描述器或手工重放 update.sql。 恢复或完成后，重新核对已安装版本、迁移账本、菜单/权限、管理端载荷和应用用户门户入口，再按本页的隔离范围执行允许、拒绝、撤销和审计检查。

卸载

先撤销业务流量、凭证和外部回调，导出需保留的审计，并确认其他插件不再依赖 SandIAM。 通过 SandPackage 执行卸载后，检查 SandIAM 文件、菜单、权限和 sand_iam_* 表已按契约清理， 同时确认宿主及其他插件未受损。不要删除宿主自有表或审计备份。

---

文档首页 · 排障

详细操作文档的维护入口统一在本 Wiki。本次源码整改后的后续构建不再复制整套指南；已公开 v0.8.3 的 1053 条目 ZIP 保留原载荷，本轮不重打包或替换发行件。离线操作前取得所选版本对应的指南。