能源数据采集平台
完整使用手册

01 · START HERE

地址与入口

02 · ACCOUNT

账号、登录与权限

门户优先使用 Authing 托管登录。使用手机号和短信验证码完成身份验证后，平台按角色开放功能。

1. 打开正式门户，选择“获取短信验证码并登录”。
2. 在 Authing 页面完成验证并返回门户。
3. 在页面顶部确认账号和角色。
4. 出现“账号等待授权”时，联系管理员分配角色；不要发送密码或验证码。

过渡环境可能仍显示页面访问码。访问码仅用于回退，不等于个人账号，也不应公开。

03 · READ DATA

查询数据库中的现有数据

先从“数据目录”找到准确 ID

1. 在首页找到“只读数据 API”。
2. 选择“数据目录”，将返回条数设为 100。
3. 发送查询并复制需要的 source_id。
4. 再切换到“指标数据”或“文档元数据”。
5. 填写 ID、开始日期、结束日期和返回条数。

查询为零时

切换到“覆盖统计”，核对该来源的记录数、最早日期和最晚日期。零记录不等于故障，也可能是日期不在覆盖范围或上游尚未发布。

04 · COLLECT

发起采集任务

1. 使用 operator 或 admin 账号登录。
2. 展开“采集任务”，写清能源主题和完整日期。
3. 需要精确控制时，展开“指定数据源”并勾选来源。
4. 提交任务后保持页面打开，等待全部子任务完成。
5. 记录 run_id，核对发现、新增、跳过和失败数量。

可以直接复制的要求

采集2025年1月1日至2025年3月31日的国家统计局月度能源生产数据。

采集2025年全年的国家能源局全社会用电量。

采集2025年第一季度的天然气价格和库存数据。

采集2026年7月1日至2026年7月31日的国家能源局政策元数据。

05 · LONG RANGE

长时间范围和分批采集

门户可以采集超过 31 天的正式数据。较长范围会按最多 30 天拆分；选择多个来源时，每个来源会得到独立子任务。

• 新数据源预览验证：最多 31 天，且不入库。
• 单个后端正式请求：默认最多 90 天。
• 门户长任务：主动拆成最多 30 天的小窗口。

多年回填建议按年、季度或月执行。保存每一批的 run_id，只重试失败窗口。

06 · DELIVERY

生成并下载标准化数据包

1. 展开“标准化数据交付”。
2. 选择“数据库现有数据”或“本次任务数据”。
3. 检索并勾选来源，设置开始和结束日期。
4. 点击“生成标准化数据包”。
5. 显示“数据包已就绪”后下载 ZIP。

网页数据包主要包含标准化 CSV 和清单，不包含原始网页、原始响应、内部配置、密钥、分析结论或摘要。下载通常在 24 小时内有效。

07 · FIND SOURCES

模糊搜索和选择数据源

在数据库导出区，可以输入来源机构、来源网站、主题或精确 ID。多个关键词用空格分开，并按“同时满足”处理。

例如输入“国家能源局 政策”，会比只输入“政策”更精确。界面仍会保留原始数据源 ID，复制时不要翻译或改名。

08 · SOURCE ADMIN

管理员添加网站、RSS 或 API

1. 进入“数据源管理”，点击“新建草稿”。
2. 填写不可变 ID、包含来源机构的显示名称、类型、类别、官方 URL 和频率。
3. 填写精确域名白名单和声明式 JSON 配置，然后保存。
4. 选择不超过 31 天且已知有数据的范围，运行预览验证。
5. 核对识别条数、字段和“未写入数据库”的提示。
6. 检查许可、频率和操作审计，再审批并启用。
7. 首次正式采集小范围，并用覆盖统计复核。

JSON API 草稿结构

{
  "source_id": "demo_oil_price",
  "source_name": "示例能源机构 - 原油价格",
  "source_type": "api",
  "category": "oil",
  "entry_url": "https://api.example.org/energy/prices",
  "frequency": "daily",
  "parser_name": "generic_api",
  "allowed_domains": ["api.example.org"],
  "config": {
    "base_url": "https://api.example.org/energy/prices",
    "query_params": {"start": "{start_date}", "end": "{end_date}"},
    "items_path": "items",
    "field_mapping": {
      "metric_name": "name", "region": "region",
      "period": "date", "value": "value", "unit": "unit"
    },
    "data_format": "json",
    "record_frequency": "daily"
  }
}

example.org 仅用于说明，不能直接审批。配置中禁止填写真实密钥、Cookie、Authorization、命令、脚本、通配域名或私网地址。

09 · DEVELOPERS

数据 API 与 Swagger

Swagger 用于查看公开 API 的路径、参数和响应结构。它不是数据展示网站，管理接口也故意不出现在其中。

curl -sS -G \
  'https://test.w2764362942.com/v1/energy/data/metrics' \
  -H 'X-Data-API-Key: YOUR_DATA_API_KEY' \
  --data-urlencode 'source_id=nbs_energy_production_monthly' \
  --data-urlencode 'start_date=2025-01-01' \
  --data-urlencode 'end_date=2025-12-31' \
  --data-urlencode 'limit=100' \
  --data-urlencode 'offset=0'

YOUR_DATA_API_KEY 是占位符。真实密钥必须通过环境变量或秘密管理服务提供，不能提交到代码仓库。

10 · OPENCLAW

OpenClaw 使用方法

OpenClaw 使用自然语言调用固定工具，只访问已批准目录，不会临时运行命令或访问任意网址。

查找与“石油”有关的已批准数据源，列出中文名称、来源网站、source_id、类型和更新频率，不要分析数据。

查询 nbs_energy_production_monthly 在 2025-01-01 到 2025-12-31 的标准化指标，返回日期、值、单位、来源网址、发布时间和采集时间。

查看 nea_electricity_consumption 的记录总数、最早日期和最晚日期，不做趋势判断。

11 · DATA MEANING

字段和时间含义

做预测模型时必须按当时已经发布的数据构造样本，避免未来信息泄露。比较数据前还要核对地区、频率、统计口径和单位。

12 · TROUBLESHOOTING

常见错误处理

13 · GUARDRAILS

安全与合规边界

• 不在聊天、截图、Git、网页代码或终端历史中写真实密钥。
• 后端密钥只保存在服务器或 Cloudflare Secrets，浏览器只访问固定门户路由。
• 不把 PostgreSQL、内部采集接口或 OpenClaw Gateway 暴露到公网。
• 不允许用户提交任意 URL、工具名、命令或请求头。
• 不绕过登录、验证码、付费墙、robots.txt 或反爬限制。
• 新闻对外只共享元数据；平台输出数据，不输出预测或决策结论。