01
创建项目、角色与接入 Token
先在管理端创建业务项目，建议按环境或团队维度拆分。项目内分配管理员、运维与只读三类成员，再生成接入 Token。Token 只展示一次，后续部署命令不建议直接保存到交付文档。
验收条件：项目下能够看到成员列表，Token 已被安全存储。
四类准入核验
版本、端口、权限与命名空间。
五个可验收步骤
每步都有明确的完成标记。
故障排查对照
按错误码和检查清单快速定位。
01 / 准备阶段
接入前需要确认的四件事
无论是在单机节点部署探针，还是通过 Helm 接入整个集群，先确认这几项基础信息都能显著降低返工概率。
02 / 操作主线
接入过程拆成五个可验收步骤
每个步骤都给出明确输入、操作内容和验收结果。项目交接时，可以直接把各步骤的完成截图与审批记录附加在文档中。
02
核对版本、网络与兼容性
根据业务组件版本选择对应接入包。使用公网环境时，运行预检命令检查内核、磁盘与出站端口；离线环境则先导入安装介质，再切换为离线模式执行预检。
验收条件：预检结果无红色告警，网络策略已记录在案。
03
部署采集组件并验证心跳
单机节点可使用交互式安装命令完成注册；Kubernetes 集群则推荐通过 Helm Chart 部署为 DaemonSet。部署完成后，立即检查“节点心跳”是否从离线变为在线。
kiactl agent install \
--project="接入指南" \
--endpoint="$KIAYUN_ENDPOINT" \
--token="$KIAYUN_TOKEN" \
--check
验收条件：目标节点在控制台显示已注册，心跳时间在 5 秒以内。
04
配置数据路由与告警目标
为不同数据源设置采集周期和标签。日志类数据可单独指定存储路径；指标与告警事件需要绑定接收人、值班组或企微群。若项目已有 Prometheus 标签体系，可在导入映射表中完成键名对齐。
验收条件：测试告警触发后，接收人能在 1 分钟内收到一次通知。
05
完成验收并交付记录
控制台确认全部目标节点在线、数据曲线连续写入后，将 Agent 版本、依赖项、网络端口、权限范围和踩坑记录整理为交付说明。后续版本升级时，这份记录会被下一轮巡检继续引用。
验收条件：交付说明可被另一名同事独立执行，无需负责人逐条解释。
03 / 场景拆分
根据运行环境选择对应入口
接入指南不是一套固定命令走到底，而是按运行方式准备好三份差异路径。
路径 A
单机与测试环境
适合首次体验或临时验证，使用交互式初始化命令，几分钟即可看到节点上线。
工具：
kiactl install
路径 B
Kubernetes 集群
通过 Helm Chart 统一管理采集组件、资源配额与命名空间，适合多节点滚动扩容。
工具：
helm install kiayun-agent
路径 C
内网与已有监控体系
面向离线软件源、内部镜像仓库或已部署 Prometheus、Zabbix 的存量环境，采用适配迁移。
方式：
离线安装包 / 标签映射配置
04 / 常见问题
接入前最常问到的几个操作细节
这些问题来自初始化失败、部署前评估和上线前检查三类真实场景。如果这里没有覆盖到具体情况，也可以直接在 kiayun官网 文档中按错误码查找对应章节。
接入是否需要独立部署一台服务器？
基础场景不需要额外规划一台服务器。kiayun官网通常通过部署在目标节点或集群内的轻量采集组件上报数据，采集组件承担转发工作，不在本地保存完整历史指标。若安装机无法直接访问公网，再准备一台内网跳板机作为安装源即可。
已有 Prometheus 或 Zabbix 监控，还能继续使用吗？
可以保留现有系统用于告警归档，kiayun官网的接入主要补充统一视图与自动化处置。采集组件使用独立端口运行，不会与既有 Agent 冲突；数据标签和命名空间在初始化阶段提前设置，不需要改动原监控体系。
节点执行 Agent 部署失败，有哪些快速排查方向？
先检查采集进程是否启动、执行用户是否拥有对应文件权限，再确认目标节点能否访问控制端的 443 或 8443 端口。如果处于内网环境，还需检查 HTTPS_PROXY 代理变量是否生效。安装脚本执行失败时会输出错误码，可对照接入清单逐步检查。
内网环境和离线状态也能完成接入吗？
能。部署包支持通过本地文件或内部软件源分发，容器组件可提前导入内网镜像仓库。初始化命令提供离线检查选项，不需要每次启动都请求公网版本服务，相关参数与前置条件在接入指南的第二步中集中列出。
接入完成后多久能看到监控数据？
采集组件注册并完成连通性校验后，控制台通常会在 2 至 3 分钟内出现第一组心跳和基础指标。如果等待 10 分钟仍无数据，建议优先检查防火墙策略、采集端时钟偏差以及 Token 绑定的项目权限。
接入手册 · 邮件摘要
把一份可以执行的接入清单留给团队
留下工作邮箱，我们会把环境变量模板、端口清单、版本兼容表和五步验收表整理成独立文档发送给你。后续版本更新或接入脚本变化，也会通过同一地址继续补充。
5 步
从零完成的接入主线
3 类
常见环境接入模板
1 份
可交接的验收记录
持续
跟读版本变化与修正