第2章 前置条件与资源准备

2.1 适用场景

本章适用于以下三类典型场景，团队可按实际角色定位参照执行：

• 新项目接入：团队首次搭建 Crash 监控体系，需要从零完成环境部署、工具选型、权限划分与数据源对接。
• 存量系统迁移：已有监控系统需要更换或升级 SDK、切换错误码映射平台、调整数据管道。
• 合规性整改：因数据安全或审计要求，需要重新梳理权限边界、数据源接入方式及记录留存规范。

2.2 前置条件

在执行本章操作前，团队必须确认已具备以下基础条件：

类别	必要条件	说明
组织	项目立项完成	已确定项目负责人、开发负责人、运维负责人及安全对接人
技术	技术方案评审通过	Crash 监控与错误码映射总体方案已完成评审并归档
资源	预算与服务器就绪	至少 1 台 4C8G 的 Linux 服务器（或同等容器配额）用于部署错误码映射平台
网络	外网与内网互通	开发环境可访问公共镜像仓库；生产环境可访问内网私有源
数据	样本 Crash 数据	至少 3 条真实或脱敏的 Crash 日志（用于后续验证映射链路）

2.3 操作步骤

2.3.1 环境准备

按照下表清单逐一检查并记录各环境的版本与状态：

检查项	最低要求	验证命令 / 方式
操作系统	Ubuntu 20.04 / CentOS 7+ / macOS 12+	uname -a
CPU 架构	x86_64 / arm64	lscpu | grep Architecture
内存	≥ 8 GB（推荐 16 GB）	free -h
磁盘	≥ 50 GB 可用空间	df -h /
网络	可访问内网镜像源 / 外网 pypi/npm	curl -I https://your-registry.com
容器（如有）	Docker 24+ / containerd 1.6+	docker --version

# 示例：快速检查环境关键信息
echo "=== OS ===" && uname -a
echo "=== CPU ===" && nproc
echo "=== MEM ===" && free -h | grep Mem
echo "=== DISK ===" && df -h / | tail -1

2.3.2 工具安装

安装以下核心工具，版本号必须锁定在已验证的兼容区间：

工具	版本要求	安装方式	用途
Crash 监控 SDK	≥ 4.2.0，< 5.0.0	内部 npm / pip 私有源	客户端 Crash 采集与上报
错误码映射平台	≥ 2.1.0，< 3.0.0	Docker 镜像部署	错误码注册、映射、查询
日志采集 Agent	≥ 1.8.0	RPM / DEB 包或容器化	Crash 日志实时采集与转发
数据校验工具	≥ 0.3.0	pip install crash-validator	映射关系正确性预检

# 示例：安装 Crash 监控 SDK（Python 项目）
pip install crash-monitor-sdk==4.2.1 --index-url https://pypi.internal.company.com/simple

# 示例：拉起错误码映射平台容器
docker pull registry.internal.company.com/error-mapper:2.1.0
docker run -d --name error-mapper \
  -p 8080:8080 \
  -v /data/error-mapper:/data \
  registry.internal.company.com/error-mapper:2.1.0

2.3.3 权限配置

按照最小权限原则，为不同角色分配对应权限：

角色	所需权限	权限范围	配置方式
开发人员	读取 Crash 详情、查询错误码映射	仅限所属应用	平台 RBAC 角色绑定
测试人员	读取 & 导出 Crash 数据、查看映射日志	测试环境全局	LDAP / OAuth 组授权
运维人员	全部读写 + 平台管理 + Agent 部署	所有环境	sudo 白名单 + 平台 admin 角色
安全审计	只读所有映射配置与操作日志	全局只读	审计专用账号 + 只读 API

# 示例：创建审计只读账号（错误码映射平台 API）
curl -X POST https://error-mapper.internal.company.com/api/v1/users \
  -H "Authorization: Bearer ${ADMIN_}" \
  -d '{
    "username": "audit_bot",
    "role": "readonly",
    "scope": "global"
  }'

2.3.4 数据源接入

将 Crash 数据源与业务数据源注册到错误码映射平台：

数据源名称	类型	接入协议	必填字段
移动端 Crash 源	Kafka 消息队列	Kafka 2.8+ SSL	app_id, crash_type, stack_hash, os_version
服务端 Crash 源	gRPC Stream	gRPC TLS 1.3	service_name, error_code, trace_id, severity
业务错误码库	MySQL 8.0	JDBC / SQLAlchemy	code, module, description, language
映射规则配置	YAML 配置文件	Git 仓库 Webhook	source_code, target_code, rule_expression

# 示例：注册一个 Kafka Crash 数据源（平台 API）
curl -X POST https://error-mapper.internal.company.com/api/v1/datasources \
  -H "Authorization: Bearer ${ADMIN_}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "mobile_crash_kafka",
    "type": "kafka",
    "config": {
      "bootstrap_servers": "kafka01.internal:9092,kafka02.internal:9092",
      "topic": "crash-events-mobile",
      "security_protocol": "SSL",
      "auto_offset_reset": "earliest"
    },
    "schema": {
      "required_fields": ["app_id", "crash_type", "stack_hash", "os_version"]
    }
  }'

2.4 输入输出物

类别	名称	来源 / 去向	格式
输入	样本 Crash 日志	业务团队 / 历史归档	JSON / Plaintext
输入	错误码业务清单	开发团队	Excel / YAML
输出	环境检查报告	本章 2.3.1	checklist_environment.md
输出	工具安装记录	本章 2.3.2	installation_log.txt
输出	权限配置表	本章 2.3.3	permission_matrix.xlsx
输出	数据源注册确认单	本章 2.3.4	datasource_registry.json

2.5 责任边界

角色	责任内容	协作接口
项目负责人	审批前置条件清单、协调资源、确认验收	周会 / 项目管理平台
开发工程师	安装 SDK、注册数据源、编写映射规则初稿	Git 仓库 / 技术文档
运维工程师	部署错误码映射平台、配置网络与容器、权限开通	工单系统 / 运维平台
测试工程师	验证环境连通性、执行预检用例、输出验收报告	测试用例库 / 缺陷管理
安全对接人	复核权限矩阵、审计数据源接入合规性	安全评审会议 / 合规平台

2.6 记录材料

本章执行过程中必须留存以下记录，归档至项目知识库 docs/02-preparation/ 目录：

• 环境检查报告（checklist_environment.md）：逐项记录各环境的版本、状态、检查人及时间戳。
• 工具安装日志（installation_log.txt）：含每条安装命令、输出摘要、版本确认结果。
• 权限配置表（permission_matrix.xlsx）：含角色、权限项、生效范围、配置人与复核人签名。
• 数据源注册确认单（datasource_registry.json）：含各数据源的接入参数、必填字段、测试结果。
• 问题跟踪表（issue_tracking.md）：记录异常处理过程中的问题描述、根因、解决措施与关闭时间。

2.7 异常处理

异常现象	常见原因	处理步骤
环境检查命令返回不兼容版本	操作系统版本过旧 / 内核参数未调优	升级系统或使用容器化环境隔离；记录差异并评估影响
SDK 安装依赖冲突	Python / Node 版本与 SDK 要求不匹配	使用虚拟环境（venv / conda）或 nvm 切换版本，锁定依赖树
错误码映射平台容器启动失败	端口占用 / 数据卷权限不足	检查端口冲突（netstat -tulpn），修正数据卷属主（chown -R 1000:1000）
Kafka 数据源接入后无消息	Topic 不存在 / SSL 证书未配置	确认 Topic 已创建且生产者已写入；检查证书链与 SAN 域名
权限配置后用户仍无法访问	缓存未刷新 / RBAC 角色未正确绑定	强制刷新平台缓存（API: POST /api/v1/cache/refresh），检查角色继承关系

# 异常处理示例：检查端口占用并释放
sudo netstat -tulpn | grep 8080
# 若被占用，停止对应进程或修改映射端口
sudo systemctl stop error-mapper
docker run -d --name error-mapper -p 8081:8080 ...

2.8 验收标准

本章全部操作完成后，由测试工程师逐项验证，满足以下所有标准方可进入下一章：

• 环境达标率 100%：所有检查项状态为 ✅，版本号在锁定范围内。
• 工具安装完整性：核心工具全部安装成功，版本号与记录材料一致。
• 权限映射正确：每个角色的权限验证用例执行通过，越权访问被正确拒绝。
• 数据源连通性：每个数据源至少成功消费 1 条测试消息，字段解析无报错。
• 记录材料完整：5 份记录材料全部归档，内容完整、签名齐全。
• 异常问题闭环：问题跟踪表中所有异常项已标记“已关闭”并附根因分析。