企业官网建设流程全解析

最近在负责一套 AWS 环境里几十台 EC2 和一组 EKS 集群的可观测性改造，目标很明确：把 AWS DevOps Agent 采集到的系统指标、日志和链路数据统一接入观测云，沉淀成一套能直接给研发运维团队看的数据面板。整个过程踩了不少坑，从 IAM 权限模型到网络边界，从 Agent 安装到观测云侧的数据校验，几乎每一层都有值得复盘的地方。这篇文章就把完整的接入过程、关键配置和排错思路整理出来，给正准备做同样事情的同学做参考。

这次改造最终跑通之后，最大的感受是：Agent 接入本身并不难，难的是提前把数据模型、权限模型和网络边界想清楚。如果一上来就急着装 Agent，大概率会在中途反复返工。所以下面我按实际推进顺序来写，从整体设计讲到每一步的实操细节，最后把几个高频问题的排查过程也放进来。

1. 接入前的整体设计与方案选型

1.1 先想清楚数据链路：Agent 到底在采集什么

很多团队第一次接触观测云时，容易把“接入 Agent”理解成一个安装动作，装上就算结束。但实际落地时，首先要回答的问题是：Agent 采集的数据从哪里来，经过什么通道，最终在观测云里以什么形态呈现。

以我这次负责的 AWS 环境为例，资源主要分三类：EC2 虚拟机和 Auto Scaling 组、EKS 容器集群、少量运行在 Lambda 上的无服务器任务。它们的可观测数据来源不同，EC2 上有系统指标、进程列表和文本日志，EKS 上除了节点指标还有 Pod 级别的事件、容器日志和 Service 访问链路，Lambda 上则更适合接收调用链和函数运行日志。

这就引出 Agent 的一个核心设计思路：它应当是一个统一的采集入口，而不是每类数据各装一个采集器。观测云的 Agent 正好承担这个角色，通过插件方式同时采集系统指标、日志、容器数据和链路信息，然后把数据统一上报到工作空间。这样做的好处很明显，运维侧不需要维护多套采集组件，研发侧看到的数据也能在一个时间轴上对齐。

我在接入前专门花了一天时间梳理数据源清单，给每个数据源标上采集方式、采集频率和数据保留周期。这一步看起来繁琐，但后续配置 Agent、建立仪表盘和配置告警时都派上了用场，否则很容易出现指标和日志各看各的，链路数据又没有关联维度的情况。

1.2 两种典型接入方式：Agent 直采与云监控拉取

在 AWS 场景下，观测云的数据接入大体上有两条路：一条是把 Agent 部署到 AWS 资源上，由 Agent 直采数据后上报；另一条是通过观测云与 AWS 的集成能力，直接调用云监控相关的 API 拉取实例指标。两条路各有适用场景，我简单对比一下。

Agent 直采的优势是覆盖面广、实时性强。除了 CPU、内存、磁盘这类云监控也有的指标，它还能采集日志内容、进程状态、端口连通性、容器事件和链路数据，而且采集间隔可以控制在秒级，对 DevOps 实践中的发布监控、异常定位更有价值。缺点是需要维护 Agent 本身的部署、升级和故障恢复。

云监控拉取的方式，优势是部署成本低，不需要在每台机器上装 Agent，适合只想看基础资源水位、不想管理采集组件的轻量场景。缺点也很明显，拿不到日志和链路，指标维度偏少，且拉取频率受云厂商 API 限制，通常在分钟级。对于 DevOps Agent 这种强调自动化反馈的场景，分钟级延迟往往来不及发现问题。

所以我的建议是：如果你的团队已经在用观测云做统一的日志检索、链路追踪和告警，那优先选择 Agent 直采，只有对极少数无法安装 Agent 的托管资源，才退回云监控拉取作为补充。我这次的实际方案也是以直采为主，只对少数 RDS 和 ELB 这类托管组件保留 API 拉取。

1.3 权限与网络边界：接入前必须先画好的两条线

接入 AWS 资源时，最容易出问题的其实不是 Agent 本身的配置，而是“Agent 以什么身份访问 AWS API”和“Agent 的数据能否顺利出网”。这两条线如果在设计阶段没画清楚，后面排错会非常痛苦。

先说身份权限。Agent 如果部署在 EC2 或 EKS 节点上，强烈建议使用 IAM Role 而不是在配置文件里硬编码 AK/SK。原因很简单：长期密钥一旦泄露，影响面是整个账号；而 IAM Role 配合临时凭证，可以有效缩小风险范围，还能通过角色策略精确控制 Agent 具备的权限。我这次统一采用 EC2 实例角色和 EKS IRSA 两种方式，分别覆盖虚拟机场景和工作负载场景，后面专门有一节讲具体配置。

再说网络边界。Agent 上报数据需要能访问观测云的接入点，如果你的实例在私有子网且没有 NAT 网关，或者安全组没有放通 443 出方向，Agent 进程会一直显示运行中，但数据怎么都到不了观测云。排查时还容易误判成 Token 问题。这类问题最好在规划网络时就检查一遍：域名解析、出网策略、安全组规则、代理环境变量等，一次位。

2. 环境准备与 AWS 侧配置

2.1 准备 AWS CLI 并校验身份

后续所有 AWS 侧的资源配置，我基本都通过 AWS CLI 完成，所以第一步先把本地的 AWS CLI 装好并验证身份。现在 AWS CLI 已经出到 v2，安装方式很简单，Linux 和 macOS 都能用官方脚本装，Windows 也有对应的安装包。

装完后先配置默认身份。如果本机使用的是长期 AK/SK，可以执行aws configure，依次输入 Access Key ID、Secret Access Key 和默认区域。如果团队使用 SSO 或临时凭证，也可以把凭证配置在~/.aws/credentials的指定 profile 里，执行命令时通过--profile指定。

配置完成后务必先跑一条命令确认身份和权限范围：

aws sts get-caller-identity aws ec2 describe-regions --region ap-southeast-1

第一条命令会显示当前调用者的 Account ID、Arn 和 UserId，确认你用的就是预期账号和身份；第二条命令验证是否有基本的 EC2 读权限。如果这两条命令都能正常返回，说明 AWS 侧的基础访问通道是通的，后续创建角色、查询实例元数据时不会再被卡在最外层。

2.2 创建最小权限的 IAM 角色

团队如果对 AWS 权限管理有要求，比如通过了 Well-Architected 相关评审，那“最小权限”四个字几乎是硬指标。Agent 采集数据时确实需要访问一些 AWS API，比如查询实例标签、获取 Auto Scaling 组信息、读取 EKS 节点状态等，但没必要把 AdministratorAccess 挂上去。

以一个部署在 EC2 上的 Agent 角色为例，我使用的信任策略比较简单，允许 EC2 服务代入该角色：

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "ec2.amazonaws.com" }, "Action": "sts:AssumeRole" } ] }

角色本身的权限策略，按实际采集需求收敛。比如需要读取实例资源和标签时，可以给ec2:Describe*相关权限；需要访问 S3 中的日志文件时，另加对应桶的s3:GetObject和s3:ListBucket。永远遵循一个原则，只开当前需要的权限，后续缺了再加。

用 AWS CLI 创建角色也很直接，把信任策略保存成trust-policy.json，然后执行：

aws iam create-role --role-name guance-agent-role --assume-role-policy-document file://trust-policy.json aws iam attach-role-policy --role-name guance-agent-role --policy-arn arn:aws:iam::aws:policy/AmazonEC2ReadOnlyAccess

最后再把角色附加到实例上。在 EC2 控制台选中目标实例，依次点击“操作 - 安全 - 修改 IAM 角色”，选择刚才创建的角色即可。如果实例已经运行，这种附加方式无需重启实例，几秒内就能生效，Agent 后续通过实例元数据服务就能拿到临时凭证。

2.3 EKS 场景下的 IRSA 配置

容器场景比虚拟机多一层身份映射。Pod 不能直接使用 EC2 实例角色，最常见的方式是 IRSA，也就是让 Kubernetes ServiceAccount 关联到一个 IAM Role，Pod 运行时通过 OIDC 换取临时凭证。这种方式比把 AK/SK 放到 Secret 里安全得多，也符合 DevOps 的自动化管理习惯。

IRSA 配置分三步走。第一步，确认 EKS 集群已经创建了 OIDC Provider，可以用下面的命令查看：

aws eks describe-cluster --name my-cluster --query "cluster.identity.oidc.issuer" --output text

第二步，创建 IAM Role，信任策略里的 Principal 换成 EKS 的 OIDC Provider，Condition 中限制sub为指定的 ServiceAccount。这一步如果写错 namespace 或 ServiceAccount 名，Pod 代入角色时会直接失败。

第三步，在 Deployment 的spec.template.spec.serviceAccountName里指定 ServiceAccount，并在 ServiceAccount 上添加注解eks.amazonaws.com/role-arn: arn:aws:iam::123456789012:role/guance-agent-sa-role。配置完成后，进入 Pod 执行aws sts get-caller-identity，能正确返回角色信息就说明 IRSA 生效了。

我这次在 EKS 集群上调了整整一个下午才把 IRSA 跑通，最后定位到问题出在 OIDC Provider 的 thumbprint 过期，重新更新后才恢复正常。所以后面在排查 Pod 权限问题时，我建议先检查 OIDC Provider 状态，再检查 ServiceAccount 注解，不要一上来就怀疑 Agent 配置。

2.4 网络连通性检查清单

网络问题往往比权限问题更隐蔽。Agent 进程一直活着，日志没有明显报错，但工作空间里就是看不到数据，这种时候十有八九是数据根本没送出去。为避免这类情况，我在正式安装 Agent 前会先执行一轮连通性检查。

检查项主要是三条。第一，实例能否解析观测云接入点的域名，用nslookup或dig确认解析结果正常。第二，实例能否在 443 端口访问接入点地址，可以用curl -v https://<接入点域名>做一次测试，能返回 HTTP 响应就说明出网正常。第三，时间是否同步，AWS 的临时凭证签名对时间偏移非常敏感，偏差超过几分钟就会出现签名过期错误，建议提前确认 NTP 服务正常运行。

如果实例在私有子网且没有绑定公网 IP，还需要确认 NAT 网关或其它出网通道存在。安全组也要放行出站 443 端口，网络 ACL 同样不能挡。我自己踩过一个坑：单独放行了安全组，但忘了子网关联的网络 ACL 还在默认 deny 状态，结果排查了快半小时。

3. Agent 安装与配置实操

3.1 安装前要确认的四件事

到这一步，AWS 侧的身份和网络已经打通，可以开始安装 Agent 了。但别急着执行安装命令，先把下面四件事确认完，能省掉后面很多无意义的重试。

第一，确认实例的操作系统和架构。观测云的 Agent 提供多种安装包，覆盖主流 Linux 发行版、Windows 和容器镜像，架构上要区分 x86_64 和 ARM64。如果服务器是 Graviton 实例，选了 x86 的安装包，安装完会出现各种诡异进程异常。

第二，确认观测云工作空间的接入地址和 Token。Token 相当于 Agent 上报数据的身份凭证，在观测云控制台对应工作空间里可以找到。不同环境的 Token 要分开管理，比如生产环境和测试环境各用各的，避免数据串空间。

第三，检查端口和资源占用。Agent 默认会监听一个本地端口用于状态查询和数据调试，如果这个端口和业务冲突，需要在配置里改掉。资源方面，Agent 常驻内存大约在 200 到 500 MB 之间，具体看开启的采集插件数量和数据量，建议给实例预留至少 1 GB 的余量，磁盘上日志文件也要考虑滚动清理。

第四，想清楚要给这台机器打什么标签。标签是后面数据聚合和权限分级的关键维度，比如env:prod、team:payment、region:ap-southeast-1。如果标签不统一，团队看板时就得靠 IP 猜机器，相当痛苦。

3.2 Linux 实例安装 Agent

确认完上面四项，安装过程本身就比较机械了。观测云提供了一键安装脚本，也支持手动下载安装包，我习惯用脚本方式做快速验证，用包管理方式做批量交付。

以最常见的 Debian/Ubuntu 系统为例，一键安装的命令类似下面这样，核心变量是工作空间接入地址和 Token：

DK_ENDPOINT=https://<接入点域名> DK_TOKEN=<工作空间Token> bash -c "$(curl -L https://static.guance.com/installer/datakit/install.sh)"

安装完成后，服务会自动注册为 systemd 服务。用下面两条命令确认运行状态：

systemctl status datakit datakit monitor

datakit monitor是一个非常有用的交互式界面，能直接看到采集器运行状态、采集点数、错误信息和上报队列情况。如果采集器出现红色状态，基本上能从界面上直接看到原因，比如权限错误、网络超时或配置文件解析失败，省去翻日志的功夫。

对于需要批量部署的服务器，我建议把 Token 和接入点统一放在环境变量或者集中配置里下发，不要每台机器手敲，避免出现生产环境配了测试 Token 的乌龙。如果用了配置管理工具，这一步完全可以写进 Playbook 或 Terraform 模板里。

3.3 关键采集配置与标签规范

Agent 安装完成后，核心工作在配置采集器。观测云的 Agent 通过主配置文件加采集器配置的方式来启用不同数据采集能力，常见采集场景包括系统指标、日志、容器、APM 链路和安全巡检。

系统指标采集器一般默认启用，不需要额外配置，主要采集 CPU、内存、磁盘、网络和进程数据。日志采集器需要指定日志文件路径和解析规则，例如 Nginx 访问日志、应用 error.log、系统 secure 日志等，每类日志对应一套 source 和 type，方便后续在观测云侧做全文检索。

容器采集器用于 EKS 或 ECS 场景，需要让 Agent 以足够权限访问 Kubernetes API 或 Docker Socket，通过 ServiceAccount 的权限配置来控制范围。链路口径则推荐与标准协议对齐，应用侧通过 OpenTelemetry 或其它协议把 Trace 数据发给 Agent，再由 Agent 统一上报。

标签部分，我在每台主机的 Agent 配置中添加了统一的全局标签：

[global_tags] env = "prod" team = "devops" region = "ap-southeast-1"

标签的作用不仅是分类查看，更重要的是后续告警通知和仪表盘变量能基于标签做过滤。比如接收告警时只看team=devops的消息，仪表盘切换环境时用env标签维度做联动。标签规范最好在建项目初期就定好，中途改标签会导致历史数据断链，观测云的对比分析功能就发挥不出来了。

3.4 使用配置管理工具下发 Agent

如果只有一两台机器，手动安装完全没有问题，但像我们这样几十台 EC2 加一套 EKS 集群，手动配置不现实。我这次采用了 GitOps 的思路，把 Agent 的安装脚本、配置模板和标签策略全部放到代码仓库里，用自动化工具统一推送到目标实例。

一个很自然的做法是用 Terraform 管理 AWS 资源，同时用用户数据脚本在实例首次启动时自动安装并配置 Agent。用户数据脚本可以读取从 Terraform 传入的变量，比如环境、标签、Token 等，这样新扩容的实例一加入负载均衡就能自动出现在观测云的资源列表里，不需要再人工登录补装 Agent。

EKS 场景则是把 Agent 以 DaemonSet 或 Deployment 方式部署到集群中，用 Helm Chart 管理。需要监控的平台组件单独起一个 DaemonSet，采集节点指标和容器日志；需要关联业务 Trace 的，则以 Sidecar 或中心 Agent 的方式接入。发布流程走 Helm 升级，回滚也方便。整套配置都进 Git，任何改动都有审计记录，这对 DevOps 团队落地来说很重要。

4. 数据上报校验与观测云侧配置

4.1 本地自检：先确认数据已经生成

Agent 装完不代表数据已经进空间。我习惯在观测云控制台查看数据之前，先在本地做一轮自检，确认 Agent 确实采集到了数据。

最直接的方式是查看 Agent 的上报统计。通过datakit monitor界面能看到每个采集器的采集次数、字节数和错误数。如果采集器状态是绿色，且错误数为零，说明数据已经正常上报。

如果想更加精细地确认某条数据，可以通过 Agent 的调试接口查询。执行下面的命令，能看到最近一段时间内 Agent 缓存的数据包情况，判断指标、日志、对象数据是否齐全：

curl -s http://127.0.0.1:9529/stats | jq '.data'

如果采集数据为零，重点检查两部分。一是采集器配置是否真的加载了，观察 Agent 启动日志里有没有解析成功的信息。二是 Tag 是否正确匹配了采集范围，比如日志采集器指定的路径和实际日志路径不一致，就会出现采集器一直运行但采集不到内容的假象。

4.2 观测云侧核验数据接入

本地确认采集到了数据，再去观测云控制台核验数据是否真的入库。这一步一般在“基础设施”或“指标”页面里看，确认对应主机或工作负载已经出现在资源列表里，并且指标曲线正常滚动更新。

如果本地显示上报成功，但观测云侧看不到数据，优先检查 Token 和接入点是否匹配。观测云的接入地址有地域属性，Agent 配置的接入点必须和控制台提示的工作空间地址保持一致。Token 也一样，工作空间之间不通用。这里有一个小经验：在 Agent 配置里通过环境变量方式传入 Token，不同环境用不同的变量值，能有效避免串 Token。

数据入库后，建议立刻建立一个最小化的仪表盘，把 CPU 使用率、内存使用率、磁盘使用率和日志采集量这几个基础视图放上去。这样既能验证数据链路是通的，也方便后续逐步补充业务相关的视图。我之前一上来就画复杂大屏，结果数据有问题，排查时反而被一堆空视图干扰。

4.3 配置告警规则让数据产生价值

数据进了观测云，如果只满足于“能看到”，那这套系统还停留在监控阶段，离 DevOps 要求的“快速反馈”还有距离。真正让数据产生价值的，是告警规则的配置。

我这次主要配了三类告警。第一类是基础设施告警，比如 CPU 使用率超过 90% 持续 10 分钟、磁盘使用率超过 85%、进程意外退出等，这类告警直接关联到具体主机或集群，接收人一般是 SRE 和运维。第二类是日志关键字告警，比如应用日志里出现OutOfMemoryError、Connection refused这类明显异常，按服务维度分派给对应研发负责人。第三类是链路健康告警，比如某条核心链路的错误率超过阈值或 P99 延迟明显升高。这类告警往往在用户感知之前就能发现问题。

告警要避免一个常见误区：规则设得太多太碎，最后所有消息都变成了“狼来了”。比较好的做法是先只对少部分核心指标配置电话和短信级别的告警，其它都走群通知，观察一周后再根据实际效果调整阈值和聚合维度。DevOps 讲究持续改进，告警规则也不是一成不变的，每个月复盘一次告警的命中率和误报率很有必要。

5. 常见问题与排查技巧实录

5.1 高频问题速查表

在实际接入过程中，我记录了下面这些高频问题。很多问题不只在我们的环境里出现过，和同行交流时他们也踩过类似的坑，所以整理成速查表，方便团队遇到同类问题时快速定位。

这张表不能覆盖所有情况，但覆盖了 80% 的常见问题。如果按表排查没有结果，不要急着折腾配置，先把 Agent 日志打开看原始报错信息，通常会比界面状态提示更直接。

5.2 身份权限问题排查

权限问题的表现比较有迷惑性。Agent 正常运行，部分指标能采到，但某些数据就是空缺，比如实例标签、EKS 事件、ASG 信息等，这时候基本可以判断是 IAM 权限不足。

第一步先确认实例当前的真实身份。在 EC2 实例上执行：

aws sts get-caller-identity

如果返回的 Arn 里没有看到预期角色，说明实例元数据服务没有取到正确的 IAM Role，或者实例上根本没有附加角色。进一步可以查询实例元数据确认：

curl -s http://169.254.169.254/latest/meta-data/iam/security-credentials/

正常情况下，这条命令会返回角色名称。如果连接超时，可能是实例元数据服务被禁用，或实例处于较老的 VPC 子网中无法访问链路本地地址。如果角色存在但权限不到位，就要回到 IAM 策略本身检查 Action 和 Resource 的匹配。

EKS 场景的排查重点在 IRSA。先看 ServiceAccount 的注解是不是写错了环境变量里的 Role Arn，再看 IAM Role 的信任策略里的 OIDC Provider 地址和集群是否一致。一个容易忽略的点是：如果集群是后来才创建的 OIDC Provider，IAM Role 里的issuer地址可能用的是旧值，需要重新生成。

5.3 日志与链路数据缺失的排查

日志和链路数据丢失，是最容易被误判的一类问题。很多人第一反应是“云平台又丢数据了”，但实际查下来，绝大多数情况出在采集配置上。

日志缺失时先确认文件路径是否真实存在，以及运行 Agent 的用户对文件是否有读权限。很多应用日志存放在业务用户目录下，Agent 如果以 root 部署，问题不大；但如果是普通用户安装，很可能连文件列表都看不到，更别说采集。另一种情况是文件被 logrotate 切分，Agent 没正确识别新文件名，可以通过通配符方式解决。

链路数据缺失时，优先检查应用是否真的把请求代理到了 Agent 的采集端口。很多接入链路追踪的开发同学，只改了代码里的上报地址，却忘了检查网络策略是否允许访问该端口。如果 Agent 和服务不在同一台主机，还要看安全组有没有放通对应端口。

不管是日志还是链路问题，排查时都可以借助 Agent 自带的调试能力，查看最近的上报状态和错误信息。相比直接去工作空间里刷页面，这种方式反馈更实时、定位更准确。

6. 从“能采”到“好用”的进阶落地

6.1 用 GitOps 管理 Agent 配置

Agent 接入跑通只是第一步，真正让这套体系可维护，必须把所有配置纳入版本管理。我们现在把 Agent 安装脚本、配置模板、标签规范、告警规则模板全部放在一个 Git 仓库里，每次变更是代码评审、自动测试、灰度发布、全量生效的流程。

比如修改一台主机的自定义标签，传统做法是登录服务器改配置文件然后重启 Agent，在几十台机器的环境下很容易漏改。现在通过修改 Git 仓库中的配置模板，再用自动化工具统一渲染和下发，配合 CI 校验配置格式，基本不会出现配置漂移。

这里推荐把 Agent 的安装和配置也纳入 Terraform 或其它基础设施即代码工具的管理范围，而不是单独维护一套脚本。这样资源的创建、Agent 的安装和观测云侧的配置就形成一个整体，新扩容机器时不再需要人工介入，DevOps 的自动化价值才能真正体现。

6.2 把可观测性引入 CI/CD 流水线

Agent 接入观测云之后，最容易忽略的是和现有 CI/CD 流水线打通。传统的发布流程通常关注代码构建、镜像推送、应用部署，极少把“可观测性验证”作为发布门禁的一环。这次我们的做法是，在发布流水线里增加两步：

第一步是发布前检查。从观测云工作空间确认新版本涉及的机器或工作负载已经有数据上报，没有空白期的迹象。这个检查不需要太复杂，通过接口查询告警事件，确认没有新增的严重告警即可。

第二步是发布后校验。在流水线里调用观测云接口查询指定服务的错误率和 P99 延迟，如果连续几次查询都超过阈值，自动化触发回滚。这套机制把可观测性从“事后看板”变成了“发布门禁”，发布过程中的异常能够第一时间被自动化流程捕获。

当然，这一步需要在观测云侧先设置好对应的接口权限和调用凭据，同时要在流水线里配置好合理的超时和重试策略，避免因为查询接口偶发超时阻塞整个发布。一次配置完成后，后续新服务接入只需要修改服务名和指标阈值，整体维护成本很低。

6.3 定期巡检与容量规划

Agent 接入不是一锤子买卖，长期运行后需要定期巡检。我建议每月至少检查一次 Agent 的采集任务异常数、上报队列占用、磁盘缓存大小和内存使用情况。如果发现某个采集器持续报错，尽快处理，避免积累成数据链路的大面积故障。

容量规划同样重要。随着业务增长，新增的机器、日志量、指标维度都会影响 Agent 的上报压力。在核心集群上，我会给 Agent 预留额外的 CPU 和内存限额，并观察上报队列的堆积情况。一旦队列经常处于高水位，就要考虑拆分采集任务或升级实例规格，而不是等到数据开始丢弃才介入。

另外，观测云侧的数据存储和索引策略也值得定期审视。不同类型的日志和指标可以设置不同的保留周期，比如系统指标保留 30 天，业务日志保留 90 天，链路数据按需缩短。这个策略既能满足排障需求，也能控制成本，属于长期的运维新常态。

我个人的体会是，Agent 接入只是可观测性体系的一块基石，真正拉开团队之间差距的，是拿到数据之后能不能快速定位问题、能不能把数据反馈到研发流程中。AWS 环境本身提供了丰富的元数据和事件源，观测云又给了统一的数据入口，把两者用好，DevOps 这条链路才算真正跑起来。