华为云 FunctionGraph 在本项目里只承担"闹钟"职责:每天固定时刻触发一次,把请求转发给
后端已签名的内部端点 POST /internal/reminders/run。提醒的查询、去重、发信全部由后端
(app/services/email.py)完成。
FunctionGraph 定时触发器 (CRON_TZ)
└─> scripts/functiongraph/handler.py # 纯标准库,60s 超时
└─> POST {INTERNAL_REMINDER_URL}
Header: X-Cron-Timestamp / X-Cron-Signature (HMAC-SHA256)
└─> app/api/internal.py -> run_reminders()
函数内不连接 RDS / Redis / OBS,也不包含任何数据库驱动。 因此函数包只有一个文件, 不需要 vendor 目录,也不受"VPC 内无法访问 RDS"的约束影响。
FunctionGraph 定时触发器使用 6 段表达式:秒 分 时 日 月 周,不是 5 段。
| 目标 | 表达式 |
|---|---|
| 每天 08:00(北京时间) | 0 0 8 * * ? |
| 每天 08:00 与 20:00 | 0 0 8,20 * * ? |
| 每周一 09:30 | 0 30 9 ? * MON |
要点:
- 共 6 段(
秒 分 时 日 月 周),写成 5 段会被拒绝或语义错位; - "日"与"周"必须有一个是
?; - 时区由函数环境变量
CRON_TZ=Asia/Shanghai决定,不设置时默认按 UTC 解释, 08:00 会变成北京时间 16:00。
CRON_TZ=Asia/Shanghai
真实定时触发器事件大致如下(字段随控制台/版本略有差异):
{
"version": "v1.0",
"time": "2026-10-31T08:00:00+08:00",
"trigger_type": "TIMER",
"trigger_name": "Timer_daily_reminders",
"event_type": "Timer",
"event_id": "0f1c2d3e-0000-0000-0000-000000000000"
}handler.is_timer_event 接受以下任一标记(满足其一即可,便于控制台/手工测试):
| 字段 | 取值 |
|---|---|
trigger_type |
"TIMER" |
event_type |
"Timer" |
Type |
"Timer" |
其余事件(例如 HTTP 调用、测试事件 {})一律返回:
{"ok": false, "reason": "not a timer trigger"}这样可以避免误配 HTTP 触发器时把提醒任务当成接口暴露出去。
| 变量 | 必填 | 说明 |
|---|---|---|
CRON_SIGNATURE_SECRET |
是 | 与后端 CRON_SIGNATURE_SECRET 完全一致的共享密钥;只在函数配置里保存,不写进代码/仓库。 |
INTERNAL_REMINDER_URL |
是 | 后端内部端点绝对地址,例如 https://api.example.com/internal/reminders/run。 |
CRON_TZ |
建议 | Asia/Shanghai,决定 6 段 cron 的时区。 |
缺少 CRON_SIGNATURE_SECRET 或 INTERNAL_REMINDER_URL 时函数直接返回
{"ok": false, "reason": "missing configuration"},不会发起网络请求。
签名头(由 handler 生成,后端校验):
X-Cron-Timestamp: <unix 秒>
X-Cron-Signature: hex(hmac_sha256(CRON_SIGNATURE_SECRET, f"{timestamp}.{raw_body}"))
后端要求时间戳偏差 ≤ 300 秒,并且同一签名只生效一次(重放返回 200 且 sent = 0)。
手工验证签名(本地):
TS=$(date +%s)
BODY='{}'
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$CRON_SIGNATURE_SECRET" -r | cut -d' ' -f1)
curl -sS -X POST "$INTERNAL_REMINDER_URL" \
-H "Content-Type: application/json" \
-H "X-Cron-Timestamp: $TS" \
-H "X-Cron-Signature: $SIG" \
--data "$BODY"
# -> {"ok":true,"sent":N,"skipped":M,"failed":0,"replay":false}handler.py 只使用标准库(urllib.request / hmac / hashlib / json / os / time),
因此不需要 pip install、不需要 vendor 目录、不需要 layer:
cd scripts/functiongraph
zip -r functiongraph.zip handler.py控制台配置:
- 运行时:Python 3.10 及以上(与后端 3.11 语法兼容,未使用 3.11 专属特性);
- 入口函数:
handler.handler; - 超时时间:≥ 60 秒(handler 自身请求超时也是 60 秒);
- 内存 / 并发:128 MB、单实例即可(一天一次)。
本地干跑(不发起网络请求,除非已设置上面两个环境变量):
python scripts/functiongraph/handler.py
# {"ok": false, "reason": "missing configuration"} 或真实执行结果函数默认在公网网络中执行,可以直接访问公网 HTTPS 后端。
一旦给函数配置 VPC(例如为了访问内网资源),华为云会移除默认公网出口:
- 函数将无法访问公网
INTERNAL_REMINDER_URL,表现为超时 /ok: false; - 若必须留在 VPC 内,需要额外配置 NAT 网关 + 绑定 EIP 才能出公网;
- 或者把后端也放进同一 VPC,用内网域名/私网 IP 访问(此时后端仍通过自己的连接池访问 RDS)。
推荐做法:函数不加入 VPC,仅通过公网 HTTPS(或已备案域名)回调后端。
| 现象 | 原因 | 处理 |
|---|---|---|
{"ok": false, "reason": "not a timer trigger"} |
事件不是定时触发器 | 检查触发器类型/测试事件 |
{"ok": false, "reason": "missing configuration"} |
环境变量缺失 | 配置 CRON_SIGNATURE_SECRET、INTERNAL_REMINDER_URL |
401 {"detail":"未认证"} |
密钥不一致或头缺失 | 两端 CRON_SIGNATURE_SECRET 对齐 |
401 {"detail":"签名已过期"} |
主机时钟漂移 > 300s | 校准时间或检查 timestamp 单位(秒) |
503 {"detail":"提醒服务暂不可用"} |
后端提醒任务异常 | 查看后端日志(异常文本已脱敏) |
200 且 replay: true |
同一签名被重复投递 | 正常去重,无需处理 |
函数日志不会打印共享密钥或签名值;后端也只记录 sent/skipped/failed 计数。