配置指南

本指南详细说明如何配置 Home Voice Box 的所有环境变量和系统设置。

环境变量配置

必需的环境变量

ALIGENIE_NAME 和 ALIGENIE_CONTENT

天猫精灵域名校验文件配置

获取方式：

  1. 登录天猫精灵开放平台
  2. 进入技能开发 → 域名校验
  3. 复制显示的文件名和内容
ALIGENIE_NAME=your_verify_filename.txt
ALIGENIE_CONTENT=your_verify_content

HA_URL

Home Assistant 服务器地址

示例：

  • 有公网 IP：http://your-domain.com:8123
  • 使用 Cloudflare Tunnel：https://ha.yourdomain.com
  • 本地开发：http://localhost:8123
HA_URL=https://ha.yourdomain.com

HA_TOKEN

Home Assistant 长期访问令牌

获取方式：

  1. 登录 Home Assistant
  2. 点击左下角用户名
  3. 滚动到底部 → 长期访问令牌 → 创建令牌
  4. 复制生成的令牌（只显示一次）
HA_TOKEN=eyJ0eXAiOiJKV1QiLCJhbGc...

LOGIN_PATH

登录页面的访问路径，用于保护登录页面

例如：如果设置为 aaa，则只有访问 /aaa 才能进入登录页。

未认证用户访问受保护页面会跳转到首页（文档页），不会暴露登录路径。

LOGIN_PATH=aaa

安全提示：建议使用复杂且不易猜测的路径，不要使用常见的路径如 login 或 admin。

ADMIN_PASSWORD

管理员登录密码

用于访问管理页面和所有需要认证的 API 接口。

ADMIN_PASSWORD=your_strong_password_here

安全提示：请使用强密码，建议包含大小写字母、数字和特殊字符。

KV_BINDING_NAME

KV Namespace 绑定名称

用于持久化存储意图映射数据。必须与 Cloudflare Dashboard 中配置的 KV Binding 名称完全一致。

KV_BINDING_NAME=INTENTS_KV

可选的环境变量

TOMI_SECRET_KEY

天猫精灵接口验证密钥（可选，但强烈推荐设置）

用于验证天猫精灵请求的安全性。如果设置了此密钥，天猫精灵平台需要在请求头中配置相同的密钥。

请求头格式：

  • X-Tomi-Secret: your_secret_key_here
TOMI_SECRET_KEY=your_random_secret_key_here

安全提示：建议设置一个复杂的随机字符串作为密钥，并在天猫精灵平台配置相同的请求头。如果不设置此变量，接口将不进行密钥验证（不推荐生产环境）。

KV Namespace 配置

步骤 1：创建 KV Namespace

  1. 登录 Cloudflare Dashboard
  2. 选择 Workers & Pages → KV
  3. 点击 Create a namespace
  4. 输入名称（如：INTENTS_KV）
  5. 点击 Add

或使用 CLI：

wrangler kv:namespace create "INTENTS_KV"

步骤 2：绑定到 Pages 项目

  1. 在 Pages 项目页面，进入 Settings → Functions
  2. 在 KV Namespace Bindings 部分，点击 Add binding
  3. 填写：
    • Variable name：可以是任意名称（如：INTENTS_KV）
    • KV namespace：选择步骤 1 创建的 namespace
  4. 点击 Save

步骤 3：设置 KV_BINDING_NAME

在环境变量中设置 KV_BINDING_NAME，值必须与步骤 2 中的 Variable name 完全一致。

KV_BINDING_NAME=INTENTS_KV

重要：如果 KV_BINDING_NAME 与绑定名称不一致，KV 功能将无法使用。

本地开发配置

1. 创建 .dev.vars 文件

cp .dev.vars.example .dev.vars

2. 编辑 .dev.vars 文件

填入所有必需的环境变量值。注意：.dev.vars 文件已在 .gitignore 中，不会被提交到 Git。

3. 启动开发服务器

# 基本启动（不使用 KV）
npx wrangler pages dev . --ip 0.0.0.0

# 使用 KV（本地开发）
npx wrangler pages dev . --ip 0.0.0.0 --kv INTENTS_KV=your_kv_namespace_id

其中 INTENTS_KV 必须与 KV_BINDING_NAME 环境变量的值一致， your_kv_namespace_id 是你的 KV namespace ID（与生产环境使用同一个）。

生产环境配置

在 Cloudflare Dashboard 中配置

  1. 进入你的 Pages 项目页面
  2. 点击 Settings 标签
  3. 在左侧菜单选择 Variables and Secrets
  4. 在 Environment Variables 部分，点击 Add variable
  5. 为每个环境变量添加：
    • Variable name（变量名）
    • Value（变量值）
    • Environment（应用环境：Production、Preview 或 Both）
  6. 点击 Save

环境说明

  • Production：生产环境，主域名访问
  • Preview：预览环境，每个 Pull Request 的预览部署
  • Both：同时应用于生产和预览环境

验证配置

  1. 访问登录页面：https://your-domain.pages.dev/LOGIN_PATH
  2. 使用 ADMIN_PASSWORD 登录
  3. 在管理页面尝试获取设备列表，确认 HA_URL 和 HA_TOKEN 配置正确
  4. 创建一条意图映射，确认 KV 配置正确