企业官网建设流程全解析

简介：面向 Opics 系统实施、运维与开发人员，这份完整文档系统梳理了 Opics 项目的安装与维护全流程。资源为单个 doc 文档，共 1 个文件，压缩包大小 7.15MB，正文按“总体架构—系统安装—数据库与 ODBC—OSYS 批量处理—Rate Feed—ALM—报表接口—运行维护”主线展开，结构清晰便于按章节查阅。手册重点涵盖服务器、存储、网络等硬件与应用环境规划，Opics 软件安装步骤、目录权限定义、数据库创建及 ODBC 配置，并逐一说明 OSYS 批量处理任务的执行机制、Rate Feed 实时数据更新配置，以及 ALM 安装和报表系统接口对接方法。同时包含日常运行维护的关键注意事项，能帮助读者在部署阶段降低环境配置错误，在维护阶段快速定位批量任务、数据更新等常见问题。目前已有 493 人学习或下载该资料。

1. Opics 系统是什么：为什么安装顺序错了要返工一整天

Opics 这个名字常见于产线检测类项目，通常不是指某个公开软件，而是一套光学检测系统的工程代号：前端由工业相机和光源采集工件图像，中央服务端运行图像处理和算法任务，最终把检测结果和统计信息落到数据库。施工阶段最典型的问题是安装顺序颠倒——先装服务端再装数据库，或者相机驱动版本与采集卡不匹配，启动阶段反复报错，返工一天只能回滚重新来。这份安装与维护手册的核心目标，就是把从架构规划到日常维护的路径固定下来：确认组件、准备环境、按序安装、验证链路、定期维护、遇到异常能定位。它最大的价值不是让没做过的人立刻变成专家，而是让新手照着步骤能在半天空窗期内完成部署，让老手遇到现场问题时能按手册快速缩小怀疑范围。下面按我实施同类项目时最常用的落地方法展开，驱动和框架保持通用，换成你们项目实际使用的组件也能参照执行。

2. 安装前规划：先拆架构，再算硬件和存储空间

正式安装 Opics 系统前，我一般强制自己和项目组先花半天做规划。跳过规划直接装依赖，最后十有八九要返工：要么存储空间不足，服务跑了两周磁盘就满；要么服务器 CPU 核数不够，图像算法一并发就把系统拖死。安装环节出问题反而好解决，架构层面的问题一旦固化下来，调整成本会翻倍。本章把规划阶段必须拍板的几个问题梳理清楚，顺带回答“为什么不能直接对着手册敲命令”。

2.1 分清三部分：采集端、服务端、数据库的角色

Opics 系统按部署形态可以拆成三层，每一层在安装和维护时关注点完全不同，写进手册也应该分开描述。

采集端连接的是相机、光源控制器、图像采集卡这类硬件设备，负责把光信号转成数字图像，并把图像数据交给服务端处理。采集端安装最依赖硬件驱动，往往需要在操作系统层面装采集卡 SDK、相机厂商的运行时库，还要核对固件版本。服务端是核心业务进程，负责接收图像、调用算法、产生检测结果、对外提供查询接口，通常以一个常驻进程的方式运行，可能还伴随几个辅助 Worker 进程。数据库层常见的是 MySQL、PostgreSQL 这类关系型数据库，存的是检测记录、任务配置、用户信息和报表聚合数据。

这三部分的安装顺序我强烈建议定为“数据库先于服务端，服务端先于采集端”。原因是：服务端启动时一定会去连数据库验证连接串，如果数据库没就绪，服务端要么启动失败，要么带病启动只报一个模糊错误。采集端联调放在最后，因为它的配置需要依赖服务端已经暴露的接口地址、端口和算法任务编号。反过来装，你会在采集端配置一个根本不存在的服务地址，然后排查半天，还很难相信自己填错了业务地址。

从维护角度看，三个组件也有不同的生命周期。数据库要关心定时备份、慢查询和连接数；服务端要关心进程存活、日志增长和内存变化；采集端要关心相机连接是否松动、光源亮度是否衰减、采集卡散热是否异常。写成同一份手册时，这三块的篇幅和检查频率应该分开列，而不是混在一起，否则运维人员每次巡检都不知道真正该盯什么。

2.2 算清服务器配置和存储容量：按产出数据量倒推

服务器配置不能照抄别人项目的推荐值，因为 Opics 系统最核心的变量是“单位时间处理多少张图像、每张图像多大”。算法复杂度决定了 CPU 占用，图像分辨率决定内存，图像保留策略决定磁盘选型和容量。我一般用一个简单的容量模型来倒推：单日新增数据量等于单张图像大小乘以每分钟检测数量乘以 60 再乘以每日开机时长。

举例来说，一张 2MB 的工件图像，产线每分钟检测 30 张，设备运行 20 小时，那么单日新增约 72GB；如果按工艺要求保留 30 天，本地存储就是 2.1TB，再留出 30% 的安全余量，至少准备 2.8TB。如果图像还要同步到分析服务器做二次复检，本地可以只保留近期数据，但这需要在安装前就明确并写进手册，否则后续没人敢删历史文件，磁盘迟早被拖垮。内存方面，服务端进程一般会把最近几分钟的图像缓存在内存里用于拼接和异常重试，16GB 是单机版起点，但跑深度学习模型时建议 32GB 起步，因为模型加载本身就要占掉好几个 GB。

CPU 按核数和主频同时考虑，有些模型吃单核性能，核心数多但主频低并不占优。数据库单独放在一块 SSD 上是底线，机械盘扛并发写入时会直接拖慢整个检测节拍。我把常见配置整理成一张参考表，方便你们落地时直接改数字：

这张表没有包含 GPU 推理卡之类的加速设备；使用 GPU 做推理的版本要额外留出显存和电源余量，服务器电源余量不足会导致 GPU 掉卡，这类故障在日志里往往表现为 CUDA 初始化失败。建议在项目手册里为每套环境单独填一张相同的表，而不是直接沿用上一项目的模板，因为填表的过程本身就能暴露容量风险，我见过不止一次“照着上个项目买服务器结果磁盘三天就满”的情况。

2.3 操作系统和依赖准备：缺了哪个库都会在前面等着你

Opics 服务端多数按 Linux 环境交付，我习惯用 Ubuntu Server 或 CentOS 这类稳定发行版，安装时选择最小化安装，不带图形界面，减少不必要的网络服务占用资源。以下是 Debian/Ubuntu 系常用的依赖准备命令，直接把这几个动作放脚本里执行更省事：

sudo apt update sudo apt install -y build-essential gcc g++ make cmake sudo apt install -y libjpeg-dev libpng-dev libtiff-dev sudo apt install -y ffmpeg sudo mkdir -p /opt/opics/{app,logs,conf,data} sudo chown -R opics:opics /opt/opics

这里每条命令都有明确目的：build-essential 提供编译工具链，因为在现场有时要现场编译部分算法模块，而不是只能下载预编译包；libjpeg、libpng、libtiff 是图像编解码底层库，Opics 系统读取和保存各类图像格式都要依赖它们；ffmpeg 通常用于视频流和图像序列转码，如果检测过程需要录像留证，这一步省不了。目录结构里 app 放服务端程序，logs 放运行日志，conf 放配置文件，data 放图像和临时文件，分开存放便于后续配置 logrotate 和备份策略。

网络端口也要提前确认：服务端对外提供接口的端口，常见是 8080 或 8443；数据库监听 3306 或 5432。如果服务端和数据库不在一台机器上，需要在防火墙上单独放行，并且数据库地址只用内网监听，别把数据库端口暴露到业务网段之外。采集端通常通过服务端端口回传图像，这个方向的访问也要保留。我在现场见过因为防火墙默认策略导致采集端发不出图像的案例，排查时要从两端各自验证端口通不通，而不是只看服务端日志。端口不通的问题，用 telnet 或 nc 从两端互测一次就能定位，不用把时间耗在怀疑服务进程上。

2.4 权限和账号：安装账号与服务运行账号分离

不少实施工程师图省事，拿 root 用户启动全部服务，这在生产环境是给自己埋雷：一旦服务端进程被利用，攻击者直接拿到整个系统权限；而且 root 运行的服务日志、临时文件全混在系统目录里，后续按用户做审计时也分不清。我的习惯是创建两个维度：一个安装账号用于拷贝文件、修改配置，一个服务运行账号用于启动服务端进程，两者权限严格分开。

sudo useradd -r -s /sbin/nologin opics sudo passwd -l opics sudo usermod -aG video opics sudo mkdir -p /var/log/opics sudo chown opics:opics /var/log/opics

代码解释：-r 创建系统账号，不作为普通登录用户；-s /sbin/nologin 禁止该账号登录 shell；passwd -l 锁定密码，防止有人尝试通过登录方式切换到这个账号。加入 video 组是为了让服务端有权限访问视频采集设备接口，如果采集端要通过串口控制光源或编码器，还需要再加入 dialout 组。运行账号不需要能登录系统，只需要对日志目录、配置目录和图像存储目录拥有读写权限即可。数据库账号同样要独立命名，不能直接拿数据库超级用户给服务端连接；为 Opics 系统创建专用账号，只授予业务库的 SELECT、INSERT、UPDATE、DELETE 权限，不给全局管理权限。这样就算服务端配置泄露，攻击面也被限制在单业务库范围内，而不是整个数据库实例都裸奔。

3. 从零安装 Opics 系统：顺序、命令与首次自检

环境准备完成后，安装工作最好保持严格顺序：数据库、服务端、采集端。每一步安装完成都要有一个“可验证”的状态，而不是装完直接跳到下一步。下面从实际命令开始写，所有路径和账号按上一章的规划来。

3.1 先初始化数据库：字符集、账号和连接串

数据库是 Opics 系统最先要起来的组件，这里以 MySQL 为例，因为产线上这套系统用 MySQL 的比例很高。安装好数据库服务后，不要急着连上去建表，先把字符集和时区定下来；否则后续检测结果里如果包含中文缺陷类别，或者设备型号包含特殊符号，会出现乱码或写入失败，这类问题到后期才暴露，排查成本是最高的。

CREATE DATABASE `opics_db` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; CREATE USER 'opics_user'@'%' IDENTIFIED BY '这里填强密码'; GRANT SELECT, INSERT, UPDATE, DELETE ON opics_db.* TO 'opics_user'@'%'; FLUSH PRIVILEGES;

这组 SQL 的顺序不能乱：先建库再建用户，最后授权。字符集选择 utf8mb4 而不是 utf8，因为 utf8 在 MySQL 中最多只支持三个字节编码，像 emoji 这类四字节字符会写不进去，设备名称或备注里一旦出现这类字符，整条插入就会失败。用户 host 用了 %，表示允许从任意 IP 连接，这是开发环境常见写法；生产环境建议收紧为服务端所在机器的内网 IP 或网段，否则数据库等于对整个内网开放，安全隐患不小。

库建好后，把连接串填到服务端配置文件 app.yml，关键参数是 URL 里追加 characterEncoding=utf8mb4，以及关闭 SSL 校验。前者保证写入时按 UTF-8 编码处理，后者避免数据库 8.0 以上默认开启加密连接后，客户端没有配证书导致连接失败。连接池参数 minimum-idle 建议设为 2，maximum-pool-size 根据并发量给 20 到 50；不要一上来就给 200，连接池太大反而会让数据库端线程数暴涨，拖慢整体响应，而且每个连接都要占用内存和文件句柄，服务端资源也会被无谓消耗。

3.2 服务端安装：解压、配置、启动与验证一条龙

服务端通常以压缩包交付。解压后先看包内结构，正规交付包应包含 bin、conf、libs 和 sql 目录，其中 sql 目录放着建表脚本。先把基础表导入数据库，再修改配置启动服务，顺序写死，避免配置文件指向空的数据库导致初始化异常。

tar -zxvf opics-server.tar.gz -C /opt/opics/app cd /opt/opics/app/opics-server mysql -uopics_user -p opics_db < ./sql/init_schema.sql vim ./conf/app.yml

配置文件修改有三个要点：数据库连接串、服务监听端口、日志级别。日志级别很关键，首次安装时把级别从 info 改成 debug，确认一切正常后再调回 info，否则生产日志会快速增长，一晚上就能写出几 GB，排错时反而被海量信息淹没。如果服务端还需要对接算法模型文件，配置里还要写清楚模型目录的绝对路径，建议放在 data 目录下，不要放在用户家目录，避免因运行账号不同造成读不到模型文件的奇怪问题。配置完成后，先用 systemd 的 unit 文件托管进程，而不是直接前台跑，否则窗口一关服务就断了。

[Unit] Description=Opics Server Service After=network.target mysql.service [Service] User=opics Group=opics WorkingDirectory=/opt/opics/app/opics-server EnvironmentFile=/opt/opics/conf/opics.env ExecStart=/opt/opics/app/opics-server/bin/start.sh Restart=always RestartSec=5 LimitNOFILE=65536 [Install] WantedBy=multi-user.target

这里有几个参数值得说清楚。After=mysql.service 表示数据库服务就绪后再启动服务端，避免启动时连不上数据库而反复重启，造成日志刷屏和误判。EnvironmentFile 指向环境变量文件，用来存放数据目录路径、JAVA_HOME 之类不适合写进主配置的内容。Restart=always 和 RestartSec=5 是生产核心配置：进程异常退出后五秒自动拉起，不用人盯着。LimitNOFILE 调高文件描述符上限，因为服务端会同时打开大量图像文件，默认的 1024 很快就不够用，文件句柄耗尽时进程不会崩溃，但表现为各种莫名其妙的 IO 错误。

unit 文件写好后执行 daemon-reload 并启用服务。启动后必须验证，不能只看 systemctl status 显示 active：一是看日志文件里有没有出现明确的启动完成记录，二是用 curl 请求健康检查接口。日志是最真实的，状态显示 active 不代表业务就绪，可能进程在循环报错。健康检查返回 JSON 里 status 为 UP，说明数据库连接、算法模块加载、文件存储路径都正常；返回 DOWN 则看日志里的组件级失败信息，按错误缩小范围，而不是盲目重启。

3.3 采集端安装：相机驱动、光源控制器与图像链路

采集端是最容易翻车的环节，因为它同时依赖操作系统驱动、硬件固件和上层软件配置。我通常先用厂商提供的 SDK 安装脚本装好运行时库，再确认设备枚举正常，最后才配置采集端的业务参数。不同相机品牌用的底层协议差异很大，有的走 USB3 Vision，有的走 GigE Vision，还有部分用采集卡传输，但验证思路是通用的：驱动装好后确认系统看到了设备节点。

# 不同厂商 SDK 安装方式不同，此处为示意 sudo sh ./vendor_sdk_install.sh sudo dmesg | grep -i cam ls -l /dev/video*

驱动装好后，重点检查设备节点是否出现，采集卡是否被系统识别为网络接口或自定义字符设备。如果设备节点没出现，先查固件版本和驱动版本是否匹配，再查供电；工业相机对供电稳定性很敏感，劣质电源适配器会导致连接时好时坏，这种问题在日志层面通常表现为相机反复掉线重连，但硬件层面看电压又是正常的。我处理过不止一次“换个电源就好了”的情况，这类问题用仪器测波纹比反复换驱动更有效。

采集端配置中，光源控制器和相机的联动顺序值得单独拎出来。很多缺陷检测场景需要用频闪光源配合全局快门，如果相机初始化时光源控制器还没就绪，拍出来的图像要么全黑，要么亮度不均匀。配置业务参数时，要在流程里设置相机开启前先发送指令唤醒光源控制器，并预留几十到几百毫秒稳定时间。这个参数具体叫什么取决于你们使用的 SDK，但逻辑顺序必须在采集流程中写死，不能依赖人工操作“先开光源再开软件”。采集端配置完成后，人工触发一次拍照，生成的图像应该出现在 data 目录对应任务文件夹下；这一步验证的是相机到存储的完整链路。链路通了之后才去调整算法阈值，别把算法调参和链路验证掺在一起，否则图像链路问题会干扰算法调试的结论。

3.4 首次启动后自检：一张表格避免“以为装好了”

首次启动后，我习惯带着实施人员按表格逐项打钩。表格能让新人明白自己到底验收了什么，也让后面接手维护的人知道系统的正常基线长什么样。下面这张表可以直接挪到手册里作为附录，每个项目填一套实际数值。

表格最后一项是模拟系统重启来验证开机自启，这一步现场很少有人做，都是装完拔电走人，结果第二天开机发现服务没起来，原因是环境变量没生效或服务依赖顺序不对。重启验证虽然耗时几分钟，但在上线前做一次，能避免大量“早上一来系统是坏的”这类问题。第四行“检测结果写入”是算法模块联调的关键：如果图像有落盘但结果没有写入数据库，说明图像处理流程中间断了，大概率是算法 Worker 进程没起来，或者模型路径配置错误；此刻查日志优先级最高，不要在数据库端反复猜测。

4. 维护操作：日志轮转、三层备份与服务守护

系统上线后，维护的核心就三件事：让日志健康增长、让备份可恢复、让服务进程常驻。任何一件没做好，运行一个月后都会产生肉眼可见的问题。本章按这三块分别讲配置和坑，配置可以直接抄用，但参数要按实际环境调整。

4.1 日志轮转：不清理日志，磁盘迟早被写满

服务端在 debug 级别跑一天能产生几个 GB 的日志，日志轮转是必须做的第一项维护配置。Linux 下最标准的做法是使用 logrotate，不用自己写脚本定时删文件，系统会在每天的固定时间自动执行。下面是针对 Opics 日志目录的配置，放到 /etc/logrotate.d/opics 即可。

/opt/opics/logs/*.log { daily rotate 30 compress delaycompress missingok notifempty su opics opics }

配置里 daily 表示每天切割一次。rotate 30 表示保留 30 份历史日志，也就是大约一个月的量。compress 启用 gzip 压缩，旧日志体积可以缩小到原来的十分之一左右。delaycompress 表示本轮切割时不立即压缩，留到下一轮再压缩，因为日志写入进程可能还挂着旧文件句柄，立即压缩有可能压到正在写入的内容造成丢失。su opics opics 让 logrotate 以 opics 用户身份处理文件，否则默认用 root 处理可能出现权限混乱，日志文件属主被改来改去，后续服务端重新初始化日志时又要报权限错误。

配置完以后可以手动验证：先以 debug 模式检查规则是否匹配 logrotate -d，再强制轮转一次 logrotate -f，然后抽查新生成的日志文件是否还能继续写入。logrotate 本身不会导致进程重启，服务端文件句柄不变化是正常情况，所以不用因为切割日志而担心影响业务。

4.2 三层备份：配置文件、数据库、图像元数据分开处理

Opics 系统的数据可以分为三层：配置文件、数据库记录、图像文件。这三层的性质完全不同，备份策略不能混在一起搞一刀切。配置文件是服务端的 app.yml、环境变量文件、算法模型路径等，数量不大，但丢失后需要重新配置，甚至重新走联调流程；数据库记录是检测结果和统计数据，属于核心业务数据；图像文件体积最大，很多部署在本地存储仅做短期保留，并不需要全量备份。

我常用的备份脚本思路如下，按调度任务每天凌晨执行：

#!/bin/bash BACKUP_BASE=/data/backup/opics DATE=$(date +%Y%m%d) # 1) 备份配置文件 tar -czf "$BACKUP_BASE/conf-$DATE.tar.gz" /opt/opics/conf /opt/opics/app/opics-server/conf # 2) 备份数据库 mysqldump -uopics_user -p"$DB_PASS" --single-transaction \ --set-gtid-purged=OFF opics_db | gzip > "$BACKUP_BASE/db-$DATE.sql.gz" # 3) 备份图像目录当日增量 find /opt/opics/data/tasks -type f -mtime -1 -print0 \ | xargs -0 tar -czf "$BACKUP_BASE/img-$DATE.tar.gz" # 4) 清理 30 天前的备份文件 find "$BACKUP_BASE" -type f -mtime +30 -delete

脚本里值得解释的细节有三个。第一，mysqldump 配合 --single-transaction 可以在不锁表的前提下导出 InnoDB 表的快照，适合生产环境避免影响正在进行的检测写入；但如果数据库里还有 MyISAM 表，这个参数会失效，需要改为锁表备份，所以导入初始化脚本时就要确认所有表都用 InnoDB。第二，--set-gtid-purged=OFF 是用新版 MySQL 做逻辑备份经常被忽略的参数，如果开着 GTID，备份导入到另一台实例时会报 GTID 冲突，这个参数能绕开坑。第三，图像备份只取 mtime 在最近 24 小时内的文件，而不是每天全量打包，否则备份盘很快也被写满，第三层备份的精髓就是“增量底包 + 每日增量”。

备份完成后要定期做恢复演练，不演练的备份等于没有备份。我一般建议每个月抽一次维护窗口，把数据库备份导入临时实例，启动一个只读服务端验证查询接口返回正常，确认数据不是一坨无法导入的垃圾。恢复演练还能顺手验证备份文件是否损坏，及时发现磁盘坏道导致备份文件虽大但无法读取的情况。

4.3 systemd 守护：开机自启、自动拉起和资源限制

第 3 章已经配置过 systemd 单元，但维护期还可以在这之上做更多事情。systemd 提供的不止是进程启动，还有资源限制和状态监控。自动重启机制真正发挥作用的条件有两个：Restart=always 应对的是进程自身退出，机器掉电重启后服务端是否自动拉起，取决于开机 enable 是否生效。另外，某些情况下服务端因配置错误反复启动失败，systemctl 会陷入启动循环，五秒等待、再拉起、再失败。这时先把 Restart 暂时理解掉，用手动方式排查。

systemctl stop opics-server sudo -u opics /opt/opics/app/opics-server/bin/start.sh

通过在前台直接跑一次启动脚本，能直接看到程序打印的异常栈或脚本本身的报错，比反复 systemctl restart 加看日志高效得多。很多服务端程序在启动阶段遇到环境变量缺失时会很安静地退出，把错误输出到标准错误流而不是写进文件日志；前台执行等于让错误直接打在脸上，这是排错效率最高的方式。

systemd 的另一个用途是限制资源占用。如果算法模块存在内存泄漏，服务端进程会把整台机器的内存吃光，连带数据库和其他服务一起崩溃。在 unit 文件里加两个参数可以约束进程行为：

MemoryHigh=28G MemoryMax=30G TasksMax=4096

MemoryHigh 是软性上限，超过之后 systemd 会督促进程组回收内存，但不强制杀死；MemoryMax 是硬性上限，超过直接被终止。对应到 Opics 系统，如果算法侧有内存泄漏，硬上限至少能保住数据库和其他服务不跟着崩，运维有时间凌晨接到告警后从容处理。TasksMax 控制进程能创建的最大线程数，避免线程爆炸导致系统无响应。进程异常退出后，systemd 捕获到的标准输出和错误信息会保留在 journald 里，执行 journalctl -u opics-server -n 100 --no-pager 就能查看；即使是配置了文件日志的服务端，启动过程中的早期错误也常常只出现在这里，养成先看 journal 的习惯能省一半排错时间。

5. 避坑手册：Opics 系统安装维护最常见的五个翻车现场

即使是按手册一步步来，现场也总有意外。这一部分整理的五个问题是我在实施和后期维护中反复遇到的，每条按“现象 → 原因 → 解决”记录，方便你们直接按现象检索到对应章节。

5.1 现象：相机图像黑屏、条纹或整体偏暗

相机连接正常，设备节点存在，SDK 也能枚举到相机，但抓出来的图像要么全黑，要么有规律横纹，要么亮度异常偏低。大部分情况不是相机坏了，而是光源控制器没有在相机抓帧之前进入稳定状态，或者频闪光源的触发信号和相机曝光信号没有对齐；还有一种可能是曝光时间设置过短而光源亮度不足，这种问题在日志里通常表现为抓帧成功但图像平均灰度低于阈值。解决办法是把光源控制器初始化放到相机初始化之前，并在两者之间增加 200 到 500 毫秒的延时，让光源先稳定下来；然后再调整曝光参数，固定光源亮度，从大往小调节曝光，找到图像灰度曲线的拐点。遇到横纹，优先怀疑供电纹波干扰，给光源和控制端分别加隔离电源，并检查设备接地是否良好。相机和光源的时序问题在手册里必须写成固定顺序，别靠操作员手感。

5.2 现象：服务端启动失败但日志文件毫无内容

systemctl start 命令执行不报错，但状态显示 exited，查看日志目录下的文件完全没内容，或者只有几行网络连接日志。原因是服务端程序在启动早期连日志系统都还没初始化就遇到了环境变量缺失或配置文件解析失败，专门的日志文件根本没被创建，错误信息全部输出到标准输出和标准错误流。解决办法是暂时把 systemd 单元停掉，手动用运行账号执行启动脚本，屏幕上会直接显示缺哪个环境变量或哪一行配置解析失败；修好后再恢复 systemd 管理。以后遇到类似现象，不要反复翻看文件日志，先确认 journalctl -u opics-server -n 50 里有没有启动阶段的输出。我见过最典型的案例是环境变量文件里少了一个冒号，程序走了半小时无日志，最后前台执行才发现是读取数据库密码时字符串截断导致鉴权失败。

5.3 现象：数据库连接池耗尽导致系统卡死

运行一段时间后，页面打开很慢，后台日志频繁出现获取数据库连接超时或连接不可用，数据库端 CPU 飙升。最常见原因是连接池 maximum-pool-size 配置过大而数据库 max_connections 没有相应调高，或者服务端存在连接泄漏，代码里获取连接后没有归还；另一种情况是建立了大量休眠连接，客户端没有配置空闲超时，数据库端 wait_timeout 又很长，连接越积越多。解决时先看数据库端执行 SHOW PROCESSLIST，区分是 active 查询还是 sleep 连接。sleep 连接多就把服务端连接池的 idle-timeout 调小，比如 300 秒；active 查询多就去查慢查询 SQL，给结果表增加索引。同时把连接池的 maximum-pool-size 适度调小，从 50 降到 20 左右，压测确认是否够用。连接池问题在压力测试阶段容易忽略，因为请求量达不到触发上限；上线后高峰期一来就暴露，所以要提前按峰值算好。

5.4 现象：磁盘空间异常增长，一天多出几十 GB

监控告警磁盘使用率连续三天上升，实际查看发现某个目录增长量远超当初容量规划的估算。八成是日志或临时图片没有清理策略；logrotate 只覆盖了日志目录，但服务端还有自己的日志扩展目录没纳入，另外图像任务目录里常常残留算法中间结果，比如预处理后的灰度图、ROI 裁剪图，失败任务也不会自动删除，时间一长体积非常可观。解决时先用 du -sh /opt/opics/* 逐层定位最大的子孙目录，确认增长来源后，在任务配置里开启自动清理中间结果，只保留最终检测结果图，再把日志轮转周期改为按天。清理执行前务必把当晚新增数据备份一遍，避免误删后拿不到后悔药。磁盘增长问题最关键的是在监控里把每个子目录接容量增长率加上，而不是只看整盘使用率，否则定位时得多花半天。我这里有一个建议：在监控页面把 /opt/opics/data 和 /var/log/opics 各挂一条曲线，超过阈值直接看曲线就知道是哪一类数据在涨。

5.5 现象：备份到一半磁盘满了，备份任务反复失败

备份脚本前一天还能跑通，第二天开始失败，备份盘使用率 99%，备份耗时越来越长。原因通常是备份脚本把全量图像目录打包了，而图像目录里的大量历史数据本就不该保留到当天，但因为缺少清理机制，全量备份越滚越大；还有一种情况是没有对备份文件做保留期管理，备份本身的累计体积超出了备份盘容量。解决时将备份脚本改成增量策略，只打包当日变化的文件，每周做一次全量；备份盘容量告警阈值设置在 80% 而不是等到 99% 才处理，留出缓冲空间。另外检查备份脚本中删除 30 天前备份的清理命令是否真的在定时执行；如果 cron 环境没配 PATH，命令可能因为找不到可执行文件而静默失败。给脚本开头加 export PATH=/usr/bin:/bin 是最省事的兜底做法，避免因为脚本环境和交互式 shell 环境不一致导致定时任务失效。

6. 进阶：上线前做一次最长路径压测，就能避免大多数故障

安装和维护手册最终还要回答一个问题：系统现在到底稳不稳？我一般会在正式上线前做一次最长路径压测，把所有真实工作负载按最高强度连续跑 7 天，模拟生产环境中最坏的情况。这个方法不需要专门的测试平台，在一台闲置服务器上就能完成，但短时间内看不出内存泄漏和连接泄漏，跑一天没什么意义，至少三天起步，七天比较可靠。

具体做法是把服务端和数据库装在测试环境，接入一路真实可用的采集端，或者用一段预先录制的图像序列循环作为输入，让系统以峰值 1.5 倍速率持续处理图像、写入检测结果。每 2 小时记录一次关键指标：CPU 使用率、内存占用、磁盘增长速率、平均响应时间、数据库连接数和错误日志数量，也就是把日常监控要看的指标提前收一遍。压测期间每天触发一次手动数据库备份，确认备份动作在业务高峰时段不会把磁盘 IO 卡到拖垮检测流程，这个验证直接对应备份脚本的定时执行时机。如果 7 天内出现一次内存持续增长不回落，或者一次连接池耗尽，就是上线前修复的最好时机。把所有指标曲线保存下来，作为上线后运维对比的基线数据，这比临时去找“正常值”靠谱得多。

这套压测方法之所以有效，是因为很多故障不是单点功能问题，而是多个组件在长时间运行下互相影响的结果。比如日志写入和数据库备份抢磁盘 IO，服务端缓存和算法模型抢内存，这些在按小时计的功能测试里根本不会暴露。最近一次我在测试环境跑五天时，发现服务端 Worker 的数量在凌晨无声增长，直到系统内存接近耗尽才触发了 OOM，靠的就是把内存曲线和连接数曲线放在同一张图上对比，这比每天人工看日志试错快太多了。所以我现在养成一个习惯：每次处理完一个故障，就把故障现象、真正原因和修复动作写回手册的附录，加上恢复耗时，作为系统成长的操作记录。手册一旦开始更新，就不再是死文档，而是这个系统活着的检查单。这个习惯看似笨拙，半年后回看，救过我很多次，希望你也能用得上。

本文还有配套的精品资源，点击获取