简介这份资源是 Opics 系统项目配套的安装与维护手册主要面向负责系统部署、数据库接入与日常运维的技术人员。手册以单个 Word 文档交付共 1 个文件压缩包 7.15MB方便直接查阅和打印。内容按目录模块展开先介绍 Opics 系统总体架构、软硬件配置清单再分章说明系统安装步骤、目录权限定义、创建 Opics 数据库、配置 ODBC 连接以及 Opics Risk 插件的安装要点。针对运行阶段手册还讲解了 OSYS 与批量处理机制、Rate Feed 实时数据更新、ALM 模块安装、报表系统接口并覆盖常见运行维护操作能帮助读者建立从环境准备到线上运行的完整认知。当前已有 493 人学习下载既适合项目实施前梳理部署清单也适合运维人员在故障排查时快速对照参考。1. Opics 系统项目安装与维护手册为什么一套系统装起来容易维护起来翻车接手过一套别人部署的 Opics 系统服务进程都在页面就是打不开数据库连接池报错刷了一整屏。查了半天发现是安装时初始化脚本只跑了一半某个配置表的字符集跟数据库实例不一致。这种问题在安装阶段根本不会暴露等数据量上来才一起爆发。所以别看标题里挂着“安装与维护手册”真正值钱的部分不是安装而是装完之后那些没人愿意写的边界条件。这篇笔记围绕 Opics 系统的完整落地路径来写从部署前的环境摸底、安装顺序和参数设置到日常巡检、备份恢复、故障排查最后给出一个能抄的自动化维护脚本框架。适合两类人一类是要亲手部署 Opics 的工程师另一类是接手了现成系统但心里没底、想建立一套巡检和排错方法的运维。文章里的所有路径、参数和命令都按实际部署经验来写你可以在自己的环境里直接验证遇到偏差再微调。2. 安装前的摸底系统组成、环境要求和部署选型2.1 一套 Opics 到底由哪几部分组成Opics 系统不是单个程序是一组服务配合工作。常见做法是服务端加采集端或客户端的结构。服务端负责数据接入、存储、业务计算和 Web 页面展示采集端部署在数据源侧负责把数据收上来推给服务端。从进程角度看一套最少包含以下进程应用服务进程Web 服务提供管理界面和 API 入口数据接入进程接收采集端上报的数据做格式校验和预处理调度进程负责定时任务、数据归档、报表生成数据库服务保存配置数据和业务数据默认用关系型数据库如果现场数据量较大还会有一个消息队列把接入和存储解耦。安装前先画一张部署拓扑图把服务端 IP、采集端数量、数据库实例位置标清楚。我见过太多人拿到手册就开装装到一半才发现服务器端口互相不通返工成本非常高。拓扑确认之后核对每个节点的基础环境。这里有一个容易被忽略的点采集端和服务端的系统时间必须一致。Opics 的接入模块对时间戳敏感偏差超过 30 秒会导致数据归属到错误的时间窗口排查起来非常费劲。2.2 环境要求与版本兼容性先对表再动手安装手册里通常会写“支持主流操作系统”但实际部署时要严格一点。以我常用的部署组合为例组件推荐版本/配置说明操作系统64 位 Linux内核版本不低于 3.10太低的内核会有 epoll 行为差异影响接入性能数据库官方提供的初始化脚本适配的版本用与手册一致的数据库大版本避免 SQL 语法差异内存服务端不低于 8GB4GB 能跑但数据量上来后 GC 频繁页面明显卡顿磁盘系统盘与数据盘分离数据库文件和日志文件单独挂盘避免日志写满系统盘JDK/Python 运行时按手册指定版本不要盲目装最新版Opics 某些模块依赖旧版运行时行为版本问题是最容易踩的坑。举个例子数据库从 V5.7 换到 V8.0 后默认字符集校验规则变了Opics 初始化脚本里如果用了老写法可能在 V8.0 下静默失败。你看到的表象是“页面能开但中文乱码”实际是初始化时没报错但也没生效。建议安装前用一个命令把环境信息一次性收集完整# 收集部署环境信息便于与手册要求核对 hostname; uname -a; cat /etc/os-release | head -n 5 java -version 21; python3 --version 21 df -h; free -m; nproc命令逻辑第一条输出主机名、内核版本和系统发行版用于核对系统要求第二条检查运行时版本确认与手册一致第三条看磁盘、内存和 CPU 核数。拿到这些输出后对照手册里的环境要求逐项打勾不满足的先处理再开始安装不要抱着“先试试”的心态。2.3 部署选型单机、双机还是分布式采集部署架构取决于业务规模和可用性要求。Opics 最常见的部署形态有三种单机部署应用服务和数据库装在同一台机器上。适合数据量小、允许短时中断的场景比如测试环境、小型实验室。部署简单维护成本最低但一台机器挂了系统就全挂。双机部署应用服务在一台机器数据库在另一台。适合正式生产环境至少数据库挂了应用还在不会丢采集数据。这种部署下网络要求比较高两台机器之间延迟最好小于 1ms。分布式采集多个采集端分别部署在数据源侧通过专网或局域网推送到中心服务端。当采集点分布在多个物理位置时这样最合理。需要注意采集端到服务端的网络带宽和延迟带宽不够时丢包率超过 0.1% 就会影响数据完整性。选型时机要放在安装之前。双机部署的数据库配置和单机不一样安装参数也不同中途切换要改一堆配置不如一开始定好方向。我的建议是数据量每天超过 1GB 或者业务不允许中断超过 10 分钟就直接上双机别犹豫。3. 从零开始装一套 Opics分步操作与参数说明3.1 服务端安装数据库、中间件与应用服务的顺序安装顺序有讲究先装数据库并完成初始化再装应用服务和接入进程。反过来做会出现应用起来后连不上库反复报错。数据库安装完成后先建库建用户-- 创建 Opics 业务库和专用账号避免使用 root CREATE DATABASE opics DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; CREATE USER opics_user% IDENTIFIED BY 强密码占位; GRANT ALL PRIVILEGES ON opics.* TO opics_user%; FLUSH PRIVILEGES;参数说明字符集固定为 utf8mb4是因为 Opics 的业务数据会包含扩展字符。opics_user是业务账号只用它连数据库不给它额外权限避免应用被攻破后数据库裸奔。密码不要写在命令行里用变量传参更安全。数据库准备好后执行初始化脚本# 执行 Opics 初始化脚本写入表结构和基础配置数据 cd /opt/opics/scripts ./init_db.sh -h 127.0.0.1 -P 3306 -u opics_user -p-h和-P指定数据库地址和端口-u和-p是账号与密码。执行完确认脚本输出里没有 ERROR然后进数据库抽查几张核心表是否建好不要只看脚本退出码为 0 就以为成功。初始化脚本有时会把一部分错误写进日志文件而不是终端所以看一眼日志是必要的。3.2 客户端/采集端安装连接配置与首次注册采集端安装相对简单核心是连接配置。配置文件通常在/opt/opics/collector/conf/collector.ini[server] host192.168.1.10 port9502 token部署时分配的令牌 [collector] name采集点A interval30 batch_size500 retry_count5 timeout10参数说明host和port是服务端接入进程的地址。token是服务端生成的注册令牌首次连接时用于身份校验令牌错误会被直接拒绝。interval是采集间隔单位秒默认 30 秒对大多数场景够了batch_size是每次上报的数据条数网络条件好可以调大减少请求次数。retry_count和timeout是失败重试策略网络抖动时靠这两个参数兜底。配置完成后启动采集端systemctl start opics-collector systemctl enable opics-collector systemctl status opics-collector --no-pager逻辑说明start启动服务enable设置开机自启status确认进程状态。启动后看服务端是否收到注册请求收到后在服务端的管理界面里能看到采集点在线。如果采集点一直显示离线先查防火墙端口再查 token 是否复制完整。3.3 初始化配置站点、角色、数据目录与备份策略采集端连上后还需要在服务端完成初始化配置。这一步经常被当作“可选”直接跳过导致后面很多功能不可用。需要初始化的内容包括站点信息站点名称、编码、时区时区必须和采集端所在时区一致用户角色管理员账号和只读账号密码策略按内部安全规范设置数据目录业务数据、临时文件、日志文件的存储路径不要默认放在根分区备份策略数据库备份周期、保留份数、备份文件存放路径在管理界面里创建数据目录时要特别注意Opics 的数据文件默认放在安装目录下的 data 子目录。如果服务器数据盘挂在/data建议把数据目录改到/data/opics_data并把日志目录独立设置# 创建数据目录和日志目录权限交给 Opics 运行用户 mkdir -p /data/opics_data /data/opics_logs chown -R opics:opics /data/opics_data /data/opics_logs目录建好后在 Opics 的配置文件中修改数据目录路径然后重启应用服务进程使配置生效。这一步如果没做后面磁盘满了你会发现根分区被日志文件填满系统盘写满后服务直接假死。4. 日常维护巡检、日志、备份与恢复4.1 日常巡检清单每天、每周、每月分别看什么系统装上只是开始维护才是大头。我把巡检分成三个周期每个周期看的东西不同。日常巡检别等出问题再做出问题时再做是救火不是维护。每日巡检5 分钟# 查看关键进程状态和资源占用 systemctl status opics-server opics-collector --no-pager df -h | grep -E /data|/$ free -m每日看进程有没有掉、磁盘还剩多少、内存有没有持续增长。内存持续增长一般不是正常波动说明可能出现了内存泄漏或缓存未释放。每周巡检查看数据库慢查询日志执行时间超过 1 秒的 SQL 记录数量检查日志文件大小和切割情况抽查采集端的数据完整性对比采集端本地队列长度和服务端接收量每月巡检全量备份一次数据库并验证备份文件的可用性清理超过保留期限的日志和临时文件检查系统补丁和 Opics 是否有新版本评估是否升级巡检要留下记录哪怕只是在本子里写一行。没有记录就看不到趋势看不到趋势就没法在问题发生前干预。我习惯每周五下午花半小时把本周巡检结果汇总成一张表对照上周数据看变化。4.2 日志体系从日志定位问题的方法Opics 的日志分散在几个地方很多人一找日志就去翻/var/log/messages方向就错了。常见的日志路径应用服务日志在/var/log/opics/server.log记录请求处理、权限校验、业务逻辑执行情况。接入进程日志在/var/log/opics/access.log记录采集端连接、数据接收、格式校验情况。采集端日志在采集机本地路径为采集端安装目录下的logs/collector.log。日志级别通过配置文件调整默认级别是 INFO排障时可临时调为 DEBUG[log] levelDEBUG max_size100MB backup_count10levelDEBUG会输出每个数据包的处理细节定位问题很有用但磁盘占用大用完记得改回 INFO。max_size是单文件最大大小超过后自动切割backup_count是保留的旧文件数量。定位问题有一个固定的排查顺序先看采集端日志确认数据有没有发出去再看服务端接入日志确认有没有收到最后看应用服务日志确认数据有没有写进库。这个顺序可以把问题快速定位到三段中的某一段而不是瞎猜。有一次采集端显示正常但服务端数据缺失查了半天发现是采集端所在机器的时间比服务端快了 5 分钟数据全打进了未来时间窗口。4.3 备份与恢复让后悔药真的有效备份这件事做了和做对了是两码事。Opics 的备份分为逻辑备份和物理备份日常运维建议以逻辑备份为主、物理备份为辅。数据库逻辑备份# 备份 Opics 数据库到指定目录保留最近 14 份 mysqldump -h 127.0.0.1 -u opics_user -p opics \ --single-transaction --set-gtid-purgedOFF \ | gzip /backup/opics_$(date %Y%m%d_%H%M%S).sql.gz find /backup -name opics_*.sql.gz -mtime 14 -delete参数说明--single-transaction在 InnoDB 引擎下做到一致性快照备份过程中不影响业务写入--set-gtid-purgedOFF是为了让备份文件可以在其他实例上恢复。find命令清理 14 天前的备份文件保留份数看磁盘空间和业务要求最少保留两份。配置文件备份同样重要。服务端配置文件和采集端配置文件每次修改后都要备份一份。我只备份数据库不备份配置系统出问题时才发现配置文件被改得面目全非连收尸的对照物都没有。恢复演练比备份本身更关键。每季度至少做一次全量恢复演练在测试环境从备份文件恢复确认恢复出来的库能正常启动、数据数量能对上。恢复不了的备份等于没有备份。这个教训是我在一次真实故障里学到的备份文件确实存在但解压后发现文件损坏什么都救不回来。5. Opics 系统安装维护避坑指南现象、原因与解决5.1 服务启动了但页面打不开现象系统服务进程全部在运行端口也监听了但浏览器访问页面一直转圈或返回 502。原因最常见的是数据库连接池没有初始化成功。应用服务启动时数据库连不上不会直接退出进程而是反复重试此时端口已经监听看起来像正常。另一个常见原因是配置文件中绑定了错误的数据库地址应用访问的是内网 IP 而数据库实际监听在另一个地址。解决先看应用服务日志搜connection或timeout关键字。如果是数据库连接问题检查数据库账号权限是否足够、防火墙是否放通了应用服务到数据库的端口。确认无问题后重启应用服务重启后等 30 秒再访问页面。这个坑在安装阶段容易混过去因为很多安装教程要求先启动服务再配置数据源顺序反了就会出现上面这个现象。正确做法是先配置后启动别偷懒。5.2 采集端频繁掉线现象采集端状态一会儿在线一会儿离线数据时有时无服务端报表缺数据。原因第一种是网络不稳定丢包率超过一定阈值后心跳超时第二种是采集端的timeout参数设置过短服务端响应稍慢就判定超时第三种是服务端的接入进程出现了线程阻塞无法及时响应心跳。解决先 ping 采集端和服务端之间的网络延迟持续观察 5 分钟看丢包率。网络没问题就调大采集端的timeout参数从 10 秒调到 15 秒同时把retry_count从 5 调到 8。调整后观察一天如果还掉线就要查服务端接入进程的线程堆栈看是不是有阻塞。采集端频繁掉线有一个隐蔽原因采集端所在机器的内网 IP 变了但服务端还按旧的 IP 白名单校验来源地址。这时候日志里会看到连接被拒绝的记录但采集端侧完全正常。5.3 数据库文件增长过快导致磁盘写满现象磁盘空间告警数据库目录增长速度明显超出预期报表查询越来越慢。原因最常见的是采集端上报间隔过短或者batch_size过小导致数据量超过预期。另一个原因是表结构缺少索引每次查询都走全表扫描产生大量临时文件落盘到数据库目录。解决先查数据量增速统计最近一周每天的数据条数。如果确实是数据量增长要评估是否需要调整采集间隔或归档策略。如果是索引问题找到查询频次最高的字段加索引。预防这一问题的关键在安装阶段就设置好数据目录和日志目录分离并且对数据目录单独设置磁盘配额或监控告警阈值。磁盘满的后果是数据库拒绝写入Opics 的接入进程会一直重试日志文件瞬间暴涨系统完全卡死只能强制重启。5.4 升级后模块版本不匹配现象升级完成后部分功能不可用报错提示版本不兼容或者升级后旧数据无法正常读取。原因Opics 由多个模块组成模块之间存在版本依赖关系。升级时只升级了核心服务没有同步升级其他模块或者是跳版本升级旧数据格式还没转换。解决严格按照手册给定的升级顺序执行先备份数据库和配置文件再升级数据库结构最后升级应用服务。升级后立即执行一次全量数据完整性校验不要等到第二天业务报错才处理。印象比较深的一次是一位同事跳了两个版本升级界面能打开但所有历史报表都查不出来。最后只能用备份回滚白白浪费了半天时间。版本升级这种事情保守比激进安全得多不要追求一步到位。6. 进阶技巧用监控脚本把维护工作自动化维护工作最怕的不是技术难而是重复劳动让人麻木。巡检项每天都是那些手动执行很容易漏。我把常用的巡检命令封装成了一个脚本放到定时任务里每天自动跑有问题直接告警。#!/bin/bash # Opics 系统每日自动化巡检脚本 # 检查项进程状态、磁盘空间、数据库连接、数据增量 LOG_FILE/var/log/opics/check.log THRESHOLD_DISK80 DB_USERopics_user DB_PASS密码占位 DB_NAMEopics # 1. 检查进程状态 for svc in opics-server opics-collector; do if systemctl is-active --quiet $svc; then echo [OK] $svc is running $LOG_FILE else echo [FAIL] $svc is down $LOG_FILE systemctl restart $svc sleep 10 if ! systemctl is-active --quiet $svc; then echo [CRITICAL] $svc restart failed $LOG_FILE fi fi done # 2. 检查磁盘使用率 DISK_USAGE$(df /data | awk NR2 {print $5} | sed s/%//) if [ $DISK_USAGE -gt $THRESHOLD_DISK ]; then echo [WARN] /data disk usage ${DISK_USAGE}% $LOG_FILE fi # 3. 检查数据库连接和数据增量 SQLSELECT COUNT(*) FROM access_record WHERE create_time NOW() - INTERVAL 1 HOUR; TODAY_COUNT$(mysql -h 127.0.0.1 -u$DB_USER -p$DB_PASS $DB_NAME -N -e $SQL) if [ -z $TODAY_COUNT ] || [ $TODAY_COUNT -eq 0 ]; then echo [WARN] no data in last hour $LOG_FILE fi脚本逻辑分三段第一段检查两个核心进程状态挂了就自动拉起拉不起来标记 CRITICAL第二段检查数据盘使用率超过 80% 告警第三段查询最近一小时内有没有新的接入记录如果没数据说明数据链路可能断了。把这个脚本放进 cron 里每天在固定时间执行一次# 每天早上 8 点执行巡检并将结果追加到日志 0 8 * * * /usr/local/bin/opics_check.sh /var/log/opics/check.log 21自动巡检不能完全替代人工巡检。脚本只能发现结果异常比如服务停了、磁盘满了、数据不写了但发现不了趋势性问题比如响应变慢、内存持续增长这些慢慢恶化的指标。我现在的做法是脚本负责每日基础检查每周人工看一下趋势数据两头都兼顾。这套监控体系建立起来以后维护 Opics 的工作量会明显降下来。前两周可能还要频繁看日志、微调阈值后面基本就是每天扫一眼巡检结果每周做一次趋势对比。系统稳定运行是对前期投入最好的回报。另外建议维护一台与生产环境隔离的测试机专门用来做升级验证和恢复演练。每次升级先在这台机器上跑一遍完整流程确认没有兼容性问题再操作生产环境。这一步虽然多花时间但能把大部分升级风险挡在生产之外。整个操作流程走到这里从环境摸底、部署安装、参数配置到日常巡检、备份恢复、故障排查和自动化运维该有的环节都有了。维护 Opics 靠的不是什么绝活是把这些习惯性动作做扎实日志多看一眼备份多验一次升级前多想一步。希望帮到你。本文还有配套的精品资源点击获取