Generic Reader Utility 技术文档

1. 概述

1.1 镜像简介

Generic Reader Utility 是一个基于Python的通用读取工具，设计用于定期执行数据读取、诊断和系统清理任务。该工具通过定时任务自动化处理流程，并提供详细的日志记录功能。

1.2 主要用途

• 执行周期性数据读取操作
• 系统诊断与连接性检查
• 自动清理系统文件
• 生成操作日志用于审计和故障排查

2. 核心功能与特性

• 定时任务管理：支持多种频率的任务调度
• 模块化设计：包含执行器、诊断、清理等独立模块
• 日志管理：分类记录不同操作的日志信息
• 系统监控：监控系统连接性和运行状态
• 文件管理：自动维护文件存储结构，包括传出、已上传和归档目录

3. 使用场景与适用范围

• 需要定期执行数据采集的应用场景
• 嵌入式系统或服务器的自动化维护
• 需要持续监控和诊断的远程设备
• 需自动化文件管理和清理的系统环境

4. 安装与配置

4.1 Docker 部署

4.1.1 前提条件

• Docker 引擎和 Docker Compose 已安装
• 具有适当权限的 Docker 账户

4.1.2 部署步骤

1. 执行安装脚本

   ./setup.sh
   

2. 登录 Docker

   docker login
   

3. 将 Compose 文件复制到目标服务器

4. 拉取镜像

   docker-compose pull
   

5. 启动服务

   docker-compose up -d
   

6. 验证容器状态

   docker ps
   

7. 进入容器

   docker exec -it {container_id} /bin/bash
   

8. 查看定时任务

   crontabs -l
   

4.2 手动安装

4.2.1 环境准备

# 安装虚拟环境工具
pip3 install virtualenv

# 创建虚拟环境
python3 -m venv venv

# 激活虚拟环境
source venv/bin/activate

# 安装依赖包
pip install -r requirements.txt

4.2.2 测试安装

# 进入源代码目录
cd src

# 运行测试
python -m manager.test_reader

5. 目录结构与配置

5.1 必要目录创建

# 主目录结构
mkdir /ava_write/logs
mkdir /ava_write/outgoing
mkdir /ava_write/uploaded
mkdir /ava_write/archive

# 控制目录结构
mkdir /ava_write/controls
mkdir /ava_write/controls/logs
mkdir /ava_write/controls/outgoing
mkdir /ava_write/controls/uploaded
mkdir /ava_write/controls/archive

5.2 目录说明

• /ava_write/logs: 主日志目录
• /ava_write/outgoing: 待传出文件目录
• /ava_write/uploaded: 已上传文件目录
• /ava_write/archive: 归档文件目录
• /ava_write/controls: 控制相关文件目录

6. 使用方法

6.1 基本操作

启动应用程序:

cd ava_iec_reader
source venv/bin/activate
cd src 
python -m manager.execute

6.2 定时任务配置

6.2.1 用户级定时任务

编辑当前用户的crontab:

crontab -e

添加以下内容:

# 每5分钟执行一次数据读取(工作日5:00-19:00)
*/5 5-19 * * * cd /home/pi/ava_iec_reader/src/ && /home/pi/ava_iec_reader/venv/bin/python -m manager.execute >> /ava_write/logs/ava_reader.log 2>&1

# 每10分钟执行一次系统诊断
*/10 * * * * cd /home/pi/ava_iec_reader/src/ && /home/pi/ava_iec_reader/venv/bin/python -m diagnosis.diagnosis >> /ava_write/logs/diagnosis.log 2>&1

# 每天凌晨2点执行一次系统清理
0 2 * * * cd /home/pi/ava_iec_reader/src/ && /home/pi/ava_iec_reader/venv/bin/python -m cleanup.cleanup >> /ava_write/logs/cleanup.log 2>&1

6.2.2 系统级定时任务

编辑sudo级别的crontab:

sudo crontab -e

添加以下内容:

# 每30分钟执行一次连接性检查(工作日5:00-19:00)
*/30 5-19 * * * cd /home/pi/ava_iec_reader/src/ && /home/pi/ava_iec_reader/venv/bin/python -m diagnosis.connectivity >> /ava_write/logs/connectivity.log 2>&1

6.3 系统服务配置

6.3.1 创建udev规则

sudo nano /etc/udev/rules.d/95-serialdaemon.rules

添加以下内容:

KERNEL=="ttyUSB0", TAG+="systemd", ENV{SYSTEMD_WANTS}="gen_env.service"

6.3.2 创建systemd服务

sudo nano /etc/systemd/system/gen_env.service

添加以下内容:

[Unit]
Description=.env file generator
After=remote-fs.target
After=syslog.target

[Service]
WorkingDirectory=/home/pi/ava_iec_reader/src
ExecStart=/home/pi/ava_iec_reader/venv/bin/python3 -m gen_env.gen_env

启用并启动服务:

sudo systemctl enable gen_env.service
sudo systemctl start gen_env.service

7. 日志管理

所有日志文件均保存在 /ava_write/logs 目录下，主要日志文件包括:

• ava_reader.log: 主应用程序日志
• diagnosis.log: 系统诊断日志
• cleanup.log: 清理操作日志
• connectivity.log: 连接性检查日志

日志文件可通过标准文本查看工具查看:

tail -f /ava_write/logs/ava_reader.log

8. 故障排除

8.1 检查容器状态

docker ps  # 查看运行中的容器
docker logs {container_id}  # 查看容器日志

8.2 验证定时任务

crontab -l  # 查看用户级定时任务
sudo crontab -l  # 查看系统级定时任务

8.3 检查目录权限

确保应用程序对所需目录具有读写权限:

ls -la /ava_write/

8.4 查看服务状态

sudo systemctl status gen_env.service