数字档案馆系统升级全流程实操指南 零中断平滑迁移落地手册

一、升级前前置准备（必做，避免业务故障）

1.1 全量数据与环境备份

所有备份文件必须存储在非系统盘的独立备份目录，执行完成后必须校验文件完整性，避免备份失效。

• 元数据备份（MySQL为例）：执行以下命令备份档案库全量数据，禁止直接在数据库所在磁盘存放备份文件 ```bash mysqldump -u [数据库用户名] -p[数据库密码] --databases digital_archive > /data/backup/archive_db_$(date +%Y%m%d%H%M).sql ```
• 档案文件备份：如果是本地存储执行以下命令，对象存储可直接触发云厂商跨区域备份任务 ```bash tar -zcvf /data/backup/archive_file_$(date +%Y%m%d%H%M).tar.gz /data/archive/storage ```
• 旧系统包备份：直接复制当前运行的系统目录到备份路径 ```bash cp -r /opt/digital_archive /data/backup/archive_system_$(date +%Y%m%d%H%M) ```
• 备份校验：将数据库备份导入测试库执行`select count() from t_archive_file`，核对数据量和生产库一致；解压文件包抽查3-5份历史档案可正常打开。

1.2 依赖环境兼容性校验

主流数字档案馆V2.0+版本默认要求以下依赖版本，不符合的提前升级：

• JDK版本≥11：执行`java -version`查看，不符合的执行`yum install -y java-11-openjdk-devel`，编辑/etc/profile添加以下配置后执行`source /etc/profile`生效 ```bash export JAVA_HOME=/usr/lib/jvm/java-11-openjdk export PATH=$JAVA_HOME/bin:$PATH ```
• MySQL版本≥8.0、Nginx版本≥1.20：分别执行`mysql -V`、`nginx -v`查看，不符合的直接从官方镜像站下载对应版本安装：https://dev.mysql.com/downloads/mysql/、http://nginx.org/en/download.html

二、系统升级实操步骤（严格按顺序执行）

2.1 元数据结构升级

必须先在测试库执行SQL脚本，确认无报错、无数据丢失再操作生产库，通用升级脚本如下，可根据实际业务需求调整字段： ```sql -- 新增全文检索字段适配智能检索功能 ALTER TABLE t_archive_file ADD COLUMN full_text LONGTEXT COMMENT '档案OCR识别全文' AFTER file_size; -- 新增权限关联索引提升查询效率 ALTER TABLE t_permission_relation ADD INDEX idx_archive_user (archive_id,user_id); -- 补齐历史数据缺失的创建人ID字段 UPDATE t_archive_file a JOIN t_user b ON a.create_account = b.account SET a.create_user_id = b.id WHERE a.create_user_id IS NULL; ``` 执行完成后执行`select count() from t_archive_file where create_user_id is null`，返回结果为0代表数据刷入成功。

2.2 系统包替换与配置更新

• 停止旧系统服务：`systemctl stop digital-archive`，确认服务停止：`ps -ef | grep digital_archive`无返回结果即可
• 解压新版本系统包：`unzip -o /tmp/digital_archive_v2.0.zip -d /opt/`
• 修改配置文件，直接复制以下内容到/opt/digital_archive/config/application.yml，替换占位符即可 ```yaml server: port: 8080 spring: datasource: url: jdbc:mysql://127.0.0.1:3306/digital_archive?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai username: [你的数据库用户名] password: [你的数据库密码] servlet: multipart: max-file-size: 10GB max-request-size: 10GB file: storage-path: /data/archive/storage elasticsearch: host: 127.0.0.1 port: 9200 ```
• 启动新系统：`systemctl start digital-archive`，查看启动日志：`tail -f /opt/digital_archive/logs/start.log`，出现“Started DigitalArchiveApplication in X seconds”代表启动成功。

2.3 灰度流量切分

修改Nginx配置，先切10%流量到新系统验证，避免全量升级出现故障影响业务，配置示例如下： ```nginx http { split_clients "${remote_addr}AAA" $archive_upstream { 10% new_archive; old_archive; } upstream new_archive { server 127.0.0.1:8080; 新系统端口 } upstream old_archive { server 127.0.0.1:8079; 旧系统备用端口 } server { listen 80; server_name archive.yourdomain.com; location / { proxy_pass http://$archive_upstream; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } } } ``` 执行`nginx -t`校验配置无报错后，执行`nginx -s reload`生效，完成灰度切流。

三、升级效果校验（必须全量覆盖核心场景）

3.1 核心功能点校验

• 档案上传：分别上传100MB、1GB、10GB三个规格的档案文件，确认上传成功、元数据正常入库、在线预览无卡顿
• 检索功能：输入3个以上存量档案的关键词，确认返回结果和旧系统一致、响应时间≤200ms
• 权限校验：普通用户登录，确认仅能访问权限范围内的档案，无权限档案提示无访问权限
• 报表导出：导出近30天的档案入库统计报表，核对数据量和旧系统导出结果完全一致

3.2 全量流量切换

灰度验证24小时无异常、错误日志占比≤0.01%后，修改Nginx的split_clients配置，将10%改为100%，重载Nginx即可完成全量升级。

四、故障回滚方案（出现异常立即执行）

4.1 功能异常回滚

如果出现档案打不开、检索无结果等功能故障，第一步先修改Nginx配置，将proxy_pass直接指向old_archive，重载Nginx切回全部流量到旧系统；如果是数据结构问题，执行以下命令恢复数据库备份： ```bash mysql -u [数据库用户名] -p[数据库密码] digital_archive < /data/backup/[对应时间的数据库备份文件].sql ``` 恢复完成后启动旧系统，验证所有功能正常即可。

4.2 性能异常回滚

如果新系统CPU占用持续≥80%超过5分钟、接口超时率≥1%，无需排查原因，直接执行流量切回操作，避免影响业务正常使用。

五、升级后收尾操作

全量升级72小时无异常后，执行以下命令清理7天以上的旧备份文件释放磁盘空间： ```bash find /data/backup -name "archive_" -mtime +7 -delete ``` 将新系统的日志路径、端口加入监控告警规则，配置5xx错误率≥0.1%、CPU≥70%的告警阈值即可。