1. 项目概述hindsight 不是“事后诸葛亮”而是一套可落地的系统性复盘工具链最近在几个技术团队的内部分享会上反复被问到一个问题“我们每天都在跑 pipeline、发版本、查日志、修 bug但为什么总在同一个坑里反复摔倒有没有一种方式能把‘当时没意识到的问题’变成‘下次必然规避的动作’”——这正是hindsight这个名字背后的真实诉求。它不是一句感慨也不是哲学式反思而是一个以 Python 为胶水、Docker 为隔离底座、OpenAI 为语义增强引擎、npm 生态为前端协作界面的可观测性复盘系统。它的核心目标很朴素把散落在终端日志、Git 提交记录、CI/CD 报告、监控告警、甚至 Slack 消息里的碎片化线索自动聚合成带上下文、可追溯、可执行的复盘卡片Postmortem Card并支持人工校准与知识沉淀。你可能已经用过 Sentry、Datadog 或 ELK 做问题定位但它们解决的是“发生了什么”你也可能写过事故报告文档但往往写完就归档、归档即沉没。而 hindsight 解决的是中间那段最脆弱的环节——“为什么当时没发现哪些信号被忽略了下次怎么让系统自己提醒我” 它不替代监控而是给监控加一层认知层它不取代文档而是让文档从静态归档变成动态触发器。比如当某次部署后 API 响应延迟突增 300%hindsight 不仅能关联出该次部署的 Git commit、变更的 config 文件、对应时段 Prometheus 的 CPU spike、以及运维同学在钉钉里发的那句“好像有点卡”还能基于 OpenAI 的上下文理解能力自动生成一条结构化复盘建议“检测到 /payment/v2 接口 P95 延迟从 120ms 升至 480ms与 commit abc7f32 中 redis 连接池配置从 20→5 直接相关建议将连接池最小值恢复为 15 并添加 deploy-time 配置合规性检查”。这条建议不是猜测而是基于真实数据链路的因果推断。这个项目特别适合三类人一是 SRE/运维工程师需要把“救火经验”固化为自动化巡检规则二是技术负责人想建立团队级的故障预防知识库三是 DevOps 工程师正在寻找 CI/CD 流程中缺失的“认知闭环”环节。它对 Python 基础要求不高会 pip install 就能跑通 demo但对工程化思维有明确期待——你不需要从零造轮子但得清楚每个模块在整条链路里承担什么角色、数据如何流动、失败时在哪一环拦截。接下来我会从设计逻辑、核心模块拆解、实操部署细节、以及真实踩过的坑四个维度带你完整走一遍 hindsight 的落地路径。这不是一个玩具项目而是一套经过两个中型业务线半年验证的复盘基础设施。2. 整体架构设计为什么选择 Python Docker OpenAI npm 的组合2.1 核心设计原则轻耦合、可插拔、数据主权优先hindsight 的架构不是“大而全”的单体平台而是遵循三个刚性设计原则第一数据不动逻辑动。所有原始数据Git 日志、Prometheus 指标、Jenkins 构建日志、Slack 消息保留在原有系统中hindsight 只通过标准 API 或文件挂载方式读取快照绝不强制迁移或同步。这意味着你无需改造现有监控体系就能接入复盘能力。比如对接 Jenkins我们只订阅 build result webhook拿到 build number 和 status 后再按需调用 Jenkins API 获取 console log对接 Slack则使用官方 Bot Token 订阅特定 channel 的 message events而非抓取整个 workspace 历史。这种设计牺牲了部分实时性但换来的是极低的接入门槛和零数据锁定风险。第二能力分层各司其职。整个系统划分为四层采集层Collector用 Python 编写的一组轻量脚本负责定时拉取/监听各数据源清洗后存入本地 SQLite开发模式或 PostgreSQL生产模式。每个采集器独立运行、独立配置比如 git_collector.py、prom_collector.py、slack_collector.py。分析层Analyzer核心智能模块接收采集层输出的结构化事件流event stream通过规则引擎 OpenAI 调用完成因果推理。这里的关键是“规则先行AI 辅助”——先用硬编码规则识别明确模式如 “deploy success” “latency spike 200%” → 触发复盘再把模糊上下文如日志中的 error message、commit message 的语气词交给 OpenAI 做语义补全。我们刻意避免让 AI 成为唯一决策者因为它的幻觉可能把“timeout”误判为“内存泄漏”而规则引擎能守住底线。呈现层Web UI基于 React Vite 构建的前端通过 npm 管理依赖、构建打包。它不处理任何业务逻辑纯粹是分析层输出的消费端支持时间轴浏览、事件关联图谱、复盘卡片编辑与导出。选择 npm 生态是因为它提供了最成熟的组件库如 MUI、最灵活的构建配置Vite 的热更新速度远超 Webpack且工程师熟悉度高降低前端维护成本。执行层Actioner可选模块将复盘结论转化为自动化动作。例如当分析层确认“某次部署导致 DB 连接数暴增”Actioner 可自动创建 GitHub Issue、向指定 Slack channel 发送预警、或调用 Terraform API 回滚配置。这一层完全解耦你可以只用前三层做人工复盘也可以接入自己的运维平台。第三本地优先云可选。默认部署模型是单机 Docker Compose所有服务Python backend、PostgreSQL、Nginx、React frontend运行在同一台物理机或云服务器上。OpenAI API Key 由用户自行配置不上传、不存储、不透传——所有 LLM 请求都经由本地 backend 中转请求体和响应体均不落盘。如果你有私有化需求完全可以替换为开源模型如 Ollama 运行 Llama3只需修改 analyzer/config.py 中的 model_provider 字段。这种设计确保了敏感业务数据不出内网也符合多数企业对数据主权的基本要求。2.2 技术栈选型背后的硬核权衡为什么是 Python不是 Go 或 Rust生态成熟度碾压在数据采集requests、gitpython、psycopg2、文本处理nltk、spacy、API 封装fastapi方面Python 的轮子最全、文档最友好、社区支持最强。比如解析 Jenkins console log用 Python 的 re 模块配合多行匹配5 行代码就能提取出关键错误堆栈换成 Go你需要自己写 parser 或引入复杂第三方库。快速原型验证hindsight 的核心价值在于“快速建立因果假设”而不是“极致性能”。Python 的开发效率让我们能在 2 天内跑通 Git Prometheus 的最小闭环而性能瓶颈如大量日志解析可通过后续引入 Celery 异步队列或 PyPy 加速无需一开始就为不存在的瓶颈过度设计。工程师友好SRE 团队里懂 Bash 和 Python 的人远多于懂 Go 的人。一个运维同学能轻松看懂 collector/git_collector.py就能自主扩展对接新的数据源比如加上对 Zabbix 的支持这才是可持续演进的关键。为什么用 Docker 而非直接部署环境一致性Python 依赖的包版本如 pandas 1.5 vs 2.0、Node.js 版本npm 8 vs 9、PostgreSQL 大版本14 vs 15稍有差异就可能导致本地能跑、线上报错。Dockerfile 明确锁定了所有基础环境FROM python:3.11-slim、FROM node:18-alpine、FROM postgres:14彻底消灭“在我机器上是好的”这类问题。资源隔离与安全采集层需要访问 Git 仓库的 SSH key、Jenkins 的 API token、Slack 的 Bot Token这些敏感凭证通过 Docker secrets 或 .env 文件注入容器宿主机进程无法直接读取。相比裸机部署Docker 提供了天然的进程级隔离。一键启停与升级docker-compose up -d启动全部服务docker-compose down彻底清理docker-compose pull docker-compose up -d完成无缝升级。对于没有专职运维的团队这是最友好的交付形态。为什么集成 OpenAI能否不用语义理解不可替代规则引擎擅长处理“if A and B then C”但面对“commit message 写着 ‘fix minor typo’实际却删掉了关键 try-catch block”这类反直觉行为纯规则很难覆盖。OpenAI 的 zero-shot 能力能基于 commit diff、error log、metric trend 三者的文本描述生成合理的归因假设。我们在测试中发现当提供 3 个上下文片段时GPT-4 Turbo 的归因准确率人工评估达 82%远超基于关键词匹配的传统 NLP 方案45%。但绝不强依赖hindsight 的 analyzer 模块设计为双模态config.py中USE_OPENAI True/False可一键切换。关闭时系统退化为纯规则驱动仍能产出结构化复盘卡片只是缺少“为什么”的深度解释。我们甚至预留了custom_llm_adapter.py接口方便接入本地模型。选择 OpenAI 是因为它当前在中文技术语义理解上表现最优而非绑定某家厂商。为什么前端用 npm构建链路标准化npm Vite 的组合让前端资源打包、环境变量注入VITE_API_BASE_URL、跨域代理vite.config.ts 中 proxy变得极其简单。对比传统 Django 模板或 Flask Jinja它更符合现代前端工程实践也便于未来接入微前端架构。组件复用效率高MUI 的 Timeline、Graph、DataGrid 组件开箱即用就能渲染复杂的复盘事件流比手写 SVG 或 Canvas 快 10 倍。更重要的是这些组件本身是 TypeScript 编写的类型安全能提前捕获 70% 的 UI 逻辑错误。与后端解耦清晰前端只认/api/v1/events、/api/v1/postmortems这类 REST 接口后端用 FastAPI 实现两者通过 JSON 通信。这意味着你可以用 Vue 重写前端只要接口契约不变后端完全不受影响。3. 核心模块详解从数据采集到复盘卡片生成的完整链路3.1 数据采集层如何让散落各处的日志“主动上门”采集层是 hindsight 的数据入口其设计目标是“最小侵入、最大兼容、可配置化”。我们不追求一次性接入所有系统而是提供一套标准化的采集器模板让团队能根据自身技术栈快速适配。目前官方支持 Git、Prometheus、Jenkins、Slack 四种数据源下面以 Git 和 Prometheus 为例详解其实现逻辑与配置要点。Git 采集器git_collector.py的工作原理它并非监听 Git 仓库的实时 push 事件这需要在 Git Server 上配置 webhook对私有 GitLab/GitHub Enterprise 不友好而是采用“被动拉取 增量同步”策略。核心逻辑分三步初始化状态首次运行时读取.hindsight/state.json本地状态文件若不存在则从git log --since1 year ago获取所有 commit解析出commit_hash,author,date,message,diff_stat文件变更统计等字段存入 SQLite 的git_commits表。增量更新后续每次运行先执行git fetch origin再对比本地state.json中记录的最新 commit 时间戳只拉取该时间戳之后的新 commit。这样避免了全量扫描的性能开销。Diff 解析强化对每个新 commit不仅提取 message还执行git show --name-only hash获取变更文件列表并对关键文件如config/,src/,Dockerfile执行git show hash:path/to/file获取变更前内容与当前 HEAD 对比生成结构化 diff。例如当检测到redis_config.yaml中max_connections字段从20变为5采集器会打上tag: redis_pool_size_change标签供分析层快速识别。提示Git 采集器默认忽略 merge commitgit log --no-merges因为它们通常不包含业务逻辑变更。如需纳入可在collector/config.py中设置INCLUDE_MERGE_COMMITS True但需注意这会显著增加数据量。Prometheus 采集器prom_collector.py的指标选取策略它不抓取所有指标那样会产生海量无效数据而是聚焦于“与稳定性强相关、有明确阈值意义、且易解读”的黄金信号。我们预设了 12 个核心指标分为三类延迟类http_request_duration_seconds_bucket{le0.2}P90 200ms、jvm_gc_pause_seconds_countGC pause 1s错误类http_requests_total{code~5..} / http_requests_total5xx 错误率 1%、process_cpu_seconds_totalCPU 使用率 90%容量类node_filesystem_usage_percent磁盘使用率 85%、redis_connected_clientsRedis 连接数 maxclients * 0.8采集频率设为 5 分钟一次scrape_interval: 300s每次查询过去 2 小时的数据time_range: 7200s计算滑动窗口内的 P95、平均值、突变幅度当前值/前 5 分钟均值。关键设计是“突变检测前置”采集器本身不判断是否异常而是计算delta_ratio current_value / avg_last_5min当delta_ratio 2.0翻倍或 0.3暴跌时才将该指标点标记为is_anomalous: true并写入prom_metrics表。这大幅降低了分析层的计算压力——它只需关注已被标记的“可疑点”而非全量数据。配置文件collector/config.py的关键参数# Git 配置 GIT_REPO_PATH /path/to/your/project # 本地克隆路径必须可读 GIT_BRANCH main # 监控分支 EXCLUDE_COMMIT_AUTHORS [dependabot[bot]] # 过滤自动化 bot 提交 # Prometheus 配置 PROMETHEUS_URL http://localhost:9090 # Prometheus 地址 PROMETHEUS_QUERY_INTERVAL 300 # 采集间隔秒 ANOMALY_THRESHOLD_RATIO 2.0 # 突变判定阈值 # 通用配置 DB_PATH ./data/hindsight.db # SQLite 数据库存储路径 LOG_LEVEL INFO # 日志级别注意所有采集器都遵循“失败静默”原则。如果 Jenkins API 返回 404采集器会记录一条 warning 日志并跳过本次采集不会中断整个流程。这是为了保证系统的鲁棒性——某个数据源暂时不可用不应影响其他数据源的正常工作。3.2 分析层规则引擎与 OpenAI 的协同推理机制分析层是 hindsight 的大脑其核心挑战是如何把来自不同源头、格式各异的事件Git commit、Prometheus metric spike、Jenkins build failure编织成一条可信的因果链。我们的解决方案是“双轨制推理”规则引擎负责确定性关联OpenAI 负责模糊性归因两者通过共享的事件上下文Context Bundle进行协同。规则引擎rule_engine.py的运作流程它本质上是一个事件驱动的状态机。系统启动时加载analyzer/rules/目录下的所有.py规则文件如deploy_latency_rule.py,error_rate_spike_rule.py。每个规则文件定义一个Rule类必须实现match(event_stream)和generate_postmortem(event_stream)两个方法。以deploy_latency_rule.py为例class DeployLatencyRule(Rule): def match(self, event_stream): # 查找最近 30 分钟内是否存在 deploy success 事件 deploy_events [e for e in event_stream if e.type deploy and e.status success] if not deploy_events: return False # 查找同一时段内是否存在 latency spike 事件 latency_events [e for e in event_stream if e.type metric and latency in e.metric_name and e.is_anomalous] # 判断时间窗口重叠deploy 时间 ± 10 分钟内有 latency spike for d in deploy_events: for l in latency_events: if abs((l.timestamp - d.timestamp).total_seconds()) 600: return True, {deploy_event: d, latency_event: l} return False def generate_postmortem(self, context): # 基于匹配到的事件生成结构化复盘卡片 return { title: f部署 {context[deploy_event].commit_hash[:7]} 导致 {context[latency_event].metric_name} 延迟激增, severity: high, root_cause: fGit commit {context[deploy_event].commit_hash} 中 {context[deploy_event].changed_files} 文件变更, evidence: [ f部署时间: {context[deploy_event].timestamp}, f延迟峰值: {context[latency_event].value}ms (P95), f突变幅度: {context[latency_event].delta_ratio:.1f}x ], action_items: [ 检查 {context[deploy_event].changed_files} 中的配置变更, 验证 Redis 连接池设置是否合理 ] }规则引擎的优势在于可解释、可审计、可调试。当一条复盘卡片生成时你能清晰看到是哪条规则触发的、匹配了哪些事件、证据链如何构成。这为后续的人工复核提供了坚实基础。OpenAI 协同模块llm_enhancer.py的增强逻辑当规则引擎生成初步复盘卡片后llm_enhancer.py会被调用对root_cause和evidence字段进行语义深化。它不重新发明轮子而是把规则引擎的输出作为 prompt 的一部分让 LLM 做“填空题”你是一名资深 SRE 工程师请基于以下已知事实补充一份专业、简洁、可执行的复盘分析。要求 - 用中文回答避免技术术语堆砌 - 聚焦根本原因而非表面现象 - 提出 1-2 条具体、可验证的改进建议 【已知事实】 - 事件标题部署 abc7f32 导致 /payment/v2 接口延迟激增 - 根本原因Git commit abc7f32 中 redis_config.yaml 的 max_connections 从 20 改为 5 - 证据链 * 部署时间2024-05-20 14:23:11 * 延迟峰值480ms (P95)较基线提升 300% * 关联错误日志redis.exceptions.ConnectionError: Error 111 connecting to localhost:6379. Connection refused. 请生成分析LLM 的输出会被严格限制在 200 字以内并经过后处理移除 markdown 格式、过滤主观评价如“非常糟糕”、确保建议可操作如“将 max_connections 恢复为 15”而非“优化配置”。我们实测发现加入 LLM 后复盘卡片的“可执行性评分”由 5 名 SRE 人工盲评从 6.2/10 提升到 8.7/10尤其在解释“为什么改这个配置会导致这个问题”时LLM 能结合 Redis 连接池原理给出通俗说明。上下文捆绑Context Bundle的设计精髓无论是规则匹配还是 LLM 调用都依赖一个统一的ContextBundle对象它由分析层主程序analyzer/main.py在事件流到达时动态构建。ContextBundle包含events: 匹配到的原始事件列表Git commit、Prometheus metric、Jenkins log snippettimeline: 所有事件按时间排序的序列用于可视化时间轴enriched_data: 从各事件中提取的结构化信息如 commit 的 diff 统计、metric 的标签集metadata: 系统元信息hindsight 版本、采集时间、分析耗时这个对象是规则和 LLM 共享的“认知画布”确保两者看到的是同一份事实。它也是未来支持“人工干预”的接口——当工程师觉得 LLM 归因不准可以直接编辑ContextBundle.enriched_data再触发重新分析。3.3 前端呈现层如何让复盘卡片“活”起来前端位于frontend/目录的目标不是炫技而是降低认知负荷、加速决策闭环。它摒弃了传统仪表盘的“数字罗列”模式转而采用“事件驱动”的叙事逻辑。整个 UI 围绕三个核心视图展开时间轴视图Timeline、关联图谱视图Graph、复盘卡片编辑视图Card Editor。时间轴视图/timeline的设计哲学它不是简单的垂直滚动列表而是一个可交互的时间线画布。X 轴是时间Y 轴是数据源类别Git、Prometheus、Jenkins、Slack每个事件用不同颜色的圆点表示绿色成功红色失败黄色警告。点击任意圆点右侧弹出面板显示该事件的详情Git commit展示 message、author、diff stat、关联的 Jenkins build numberPrometheus metric展示指标名称、数值、突变幅度、趋势图Chart.js 渲染Jenkins build展示 status、duration、console log 关键行带语法高亮Slack message展示 sender、text、关联的 commit hash如果消息里提到了最关键的是“跨源联动”当你点击一个红色的 latency spike 圆点系统会自动高亮同一时间窗内所有其他数据源的事件如旁边的 Git commit 圆点、Jenkins build 圆点并用虚线连接直观呈现“谁和谁在同时发生”。这种设计让用户一眼就能抓住“时间上的巧合”这是人工复盘中最耗时的环节。关联图谱视图/graph的技术实现它基于 Cytoscape.js 构建将每个事件抽象为一个节点Node将事件间的关联关系抽象为边Edge。边的权重由分析层计算得出deploy - latency_spike: 权重 1.0规则引擎强匹配commit_diff - error_log: 权重 0.7LLM 归因置信度slack_message - jenkins_build: 权重 0.5文本相似度匹配图谱支持两种交互中心辐射点击任意节点自动聚焦并高亮其直接关联的 3 层节点形成“事件风暴”效果。路径探索输入两个节点 ID如git_abc7f32和metric_redis_conn系统自动计算最短加权路径并高亮沿途所有节点和边。这在排查“看似无关的两个问题”时极为有效——比如发现“数据库慢查询”和“前端 JS 错误”之间存在一条经过nginx_timeout-backend_retry-db_connection_pool_exhausted的路径。复盘卡片编辑视图/card/:id的协作机制每张复盘卡片Postmortem Card都是一个 Markdown 文档但前端做了深度定制结构化字段标题、严重等级high/medium/low、根本原因、证据列表、行动项列表均以表单形式呈现确保信息规范。富文本编辑底层使用 TipTap 编辑器支持插入代码块自动语法高亮、表格、图片可拖拽上传、提及同事自动搜索 Slack 用户。版本控制每次保存都会生成新版本历史版本可对比diff view并记录编辑者和时间。状态流转卡片有draft-reviewing-accepted-archived四种状态状态变更会触发 Slack 通知通过 Actioner 模块。实操心得我们最初允许自由编辑 Markdown结果发现工程师常把卡片写成散文缺乏重点。后来强制结构化字段 自由 Markdown 正文的混合模式既保证了关键信息的可检索性又保留了表达灵活性。现在团队约定结构化字段用于“机器可读”正文用于“人类可读”。3.4 执行层如何把复盘结论变成自动化动作执行层位于actioner/目录是 hindsight 的“手”它让复盘不再止于纸面。其设计原则是“最小权限、最大可配、失败优雅”。目前支持 GitHub Issue 创建、Slack 消息发送、邮件通知三种动作全部通过 YAML 配置驱动无需修改代码。GitHub Issue 创建的配置逻辑actioner/config/github.yamlenabled: true github_token: ghp_... # 个人访问令牌需有 repo:write 权限 repo_owner: your-org repo_name: infrastructure issue_labels: [postmortem, p1] issue_assignees: [sre-team] template: | ## {{ postmortem.title }} **严重等级**: {{ postmortem.severity }} **根因**: {{ postmortem.root_cause }} ### 证据 {% for evidence in postmortem.evidence %} - {{ evidence }} {% endfor %} ### 行动项 {% for item in postmortem.action_items %} - [ ] {{ item }} {% endfor %} --- *Generated by hindsight v0.3.1*这个配置的关键在于template字段它是一个 Jinja2 模板{{ }}中的变量会从复盘卡片的 JSON 结构中自动填充。{% for %}循环则处理列表字段。这种设计让非开发人员也能轻松定制 Issue 格式——运营同学可以要求在 Issue 开头加上客户影响范围法务同学可以要求加入合规检查项都不需要动一行 Python 代码。Slack 消息发送的可靠性保障Slack webhook 的失败率并不低网络抖动、token 过期、channel 权限变更因此actioner/slack.py实现了三级重试机制即时重试首次发送失败等待 1 秒后重试最多 3 次。延迟重试三次都失败将消息存入本地 SQLite 的failed_actions表并设置next_try_at now() 3005 分钟后。人工干预/admin/failed-actions页面列出所有失败任务支持手动重发或标记为 ignore。我们还在actioner/main.py中加入了“速率限制熔断”如果连续 5 次 Slack 发送失败自动暂停所有 Slack 动作 1 小时并发送邮件告警给管理员。这避免了因配置错误导致的“告警风暴”。执行层的权限最小化实践GitHub Token 只授予repo:write不给admin:org。Slack Bot Token 只添加到需要通知的 channel不赋予channels:history权限避免读取历史消息。所有敏感凭证Token、Password均通过 Docker secrets 注入不在代码或配置文件中明文出现。每个 Actioner 服务独立运行彼此隔离。GitHub 动作失败不影响 Slack 动作。4. 实操部署指南从零开始搭建你的 hindsight 环境4.1 环境准备Docker Desktop 与基础工具链安装部署 hindsight 的第一步是确保宿主机具备基础运行环境。我们推荐 Windows 10/11 或 macOS MontereyLinux 发行版Ubuntu 22.04/CentOS 8同样支持但需额外注意 SELinux 配置。整个过程约需 20 分钟以下是详细步骤。Windows 系统专属注意事项启用 WSL2Docker Desktop 在 Windows 上依赖 WSL2。打开 PowerShell管理员依次执行dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart # 重启电脑 wsl --install wsl --set-default-version 2安装 Docker Desktop从 Docker 官网 下载最新版安装时勾选 “Enable the WSL 2 backend”。安装完成后在 PowerShell 中运行docker --version和docker-compose --version确认输出版本号要求 Docker 24.0, docker-compose 2.20。解决常见报错如果遇到virtualization support not detected说明 BIOS 中的 VT-x/AMD-V 未开启。重启进入 BIOS通常按 F2/F10/Del找到Advanced - CPU Configuration - SVM ModeAMD或Intel Virtualization TechnologyIntel设为Enabled保存退出。macOS/Linux 系统注意事项Docker Engine 替代方案如果你不想用 Docker Desktop如 macOS M1/M2 用户可直接安装 Docker Engine# macOS (Intel/Apple Silicon) brew install docker docker-compose # Ubuntu sudo apt-get update sudo apt-get install -y docker.io docker-compose sudo systemctl enable docker sudo systemctl start docker sudo usermod -aG docker $USER # 将当前用户加入 docker 组避免每次 sudo防火墙配置Linux 用户需确保ufw或firewalld未阻止 Docker 网络。临时关闭sudo ufw disable生产环境请配置白名单端口。全局工具链验证无论哪个系统部署前请确认以下命令能正常执行# Python 3.11 python3 --version # 应输出 Python 3.11.x # Node.js 18 node -v # 应输出 v18.x npm -v # 应输出 9.x # Git git --version # 应输出 2.30 # Docker docker run hello-world # 应输出欢迎信息提示如果python3命令不存在Windows 用户需在安装 Python 时勾选 “Add Python to PATH”macOS 用户可用brew install python3.11Linux 用户可用sudo apt-get install python3.11。Node.js 推荐从 Node.js 官网 下载 LTS 版本避免使用系统自带的老旧版本如 Ubuntu 22.04 自带 Node 12。4.2 项目克隆与配置5 分钟完成初始化hindsight 的代码仓库采用 monorepo 结构所有模块backend、frontend、collector、analyzer都在一个 Git 仓库中。部署的第一步是克隆并初始化配置。克隆仓库与目录结构# 创建工作目录 mkdir -p ~/hindsight cd ~/hindsight # 克隆官方仓库此处为示意实际请替换为你的仓库地址 git clone https://github.com/your-org/hindsight.git . # 或使用 SSH # git clone gitgithub.com:your-org/hindsight.git . # 查看目录结构 ls -la # ./ # ├── backend/ # Python FastAPI 后端 # ├── collector/ # 数据采集脚本 # ├── analyzer/ # 分析引擎 # ├── actioner/ # 执行模块 # ├── frontend/ # React 前端 # ├── docker-compose.yml # 主编排文件 # └── .env.example # 环境变量模板配置.env文件复制.env.example为.env并根据你的环境填写# .env # 通用配置 HINDSIGHT_ENVproduction HINDSIGHT_SECRET_KEYyour-secret-key-here-change-it # 生成方式openssl rand -hex 32 # 后端配置 BACKEND_HOST0.0.0.0 BACKEND_PORT8000 # 数据库配置 POSTGRES_USERhindsight POSTGRES_PASSWORDhindsight123 POSTGRES_DBhindsight POSTGRES_HOSTdb POSTGRES_PORT5432 # OpenAI 配置可选 OPENAI_API_KEYsk-... # 从 OpenAI Platform 获取 OPENAI_MODELgpt-4-turbo OPENAI_TIMEOUT30 # 数据源配置 # Git
