外观
和风天气 JWT 认证配置教程
约 1434 字大约 5 分钟
2026-04-01
本教程教你如何配置和风天气的 JWT（JSON Web Token）身份认证方式。
📋 目录
什么是 JWT 认证
JWT（JSON Web Token）是一种安全的身份认证方式，比传统的 API KEY 更安全。使用 JWT 认证可以：
- 防止他人伪造你的身份
- 无需在请求中暴露 API KEY
- 提高接口调用的安全性
准备工作
开始之前，你需要：
- 一个和风天气开发者账号
- 一个已创建的项目（在和风天气控制台创建）
- OpenSSL 工具（Linux/macOS 自带，Windows 需要安装）
第一步：生成 Ed25519 密钥对
JWT 认证使用 Ed25519 算法进行签名。你需要生成一对密钥：
- 私钥：用于签名 JWT（自己保管，不要泄露）
- 公钥：上传到和风天气控制台（用于验证签名）
方法一：使用命令行（推荐）
打开终端，执行以下命令：
# 生成私钥
openssl genpkey -algorithm ED25519 -out ed25519-private.pem
# 从私钥提取公钥
openssl pkey -pubout -in ed25519-private.pem > ed25519-public.pem执行后会生成两个文件：
ed25519-private.pem- 私钥文件ed25519-public.pem- 公钥文件
方法二：使用在线工具
如果不方便使用命令行，可以使用在线工具生成：
- 访问 JWT.io 或其他 Ed25519 密钥生成工具
- 生成密钥对
- 将私钥和公钥分别保存为
.pem文件
查看密钥内容
# 查看私钥
cat ed25519-private.pem
# 查看公钥
cat ed25519-public.pem私钥内容示例：
-----BEGIN PRIVATE KEY-----
MC4CAQAwBQYDK2VwBCIEIPxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-----END PRIVATE KEY-----公钥内容示例：
-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=
-----END PUBLIC KEY-----第二步：上传公钥到和风天气控制台
2.1 登录控制台
访问 和风天气控制台，登录你的账号。
2.2 选择项目
在项目列表中，点击你需要添加凭据的项目名称。
2.3 添加凭据
- 找到「凭据」区域
- 点击右侧的「添加凭据」按钮
- 选择身份认证方式：JSON Web Token
- 输入凭据名称（如：我的网站）
- 粘贴公钥内容（完整复制，包括
-----BEGIN PUBLIC KEY-----和-----END PUBLIC KEY-----） - 点击「保存」
2.4 记录重要信息
保存成功后，控制台会显示：
- 凭据ID（kid）：如
ABC123DEF456 - SHA-256：用于验证公钥是否正确
请记录凭据ID，后面会用到。
第三步：获取凭据ID和项目ID
在配置网站之前，你需要获取两个重要参数：
3.1 项目ID（Sub ID）
- 在 控制台-项目管理
- 点击项目名称
- 页面上会显示 项目ID（如
XYZ789ABC123）
3.2 凭据ID（Key ID）
- 在项目详情页的「凭据」区域
- 可以看到你创建的凭据
- 凭据列表中显示的就是 凭据ID（如
ABC123DEF456）
第四步：填写网站配置
现在你可以在网站后台填写和风天气配置了。
4.1 配置项说明
| 配置项 | 说明 | 示例值 |
|---|---|---|
| API Host | 和风天气 API 域名 | devapi.qweather.com |
| Key ID (kid) | 凭据ID | YOUR_KEY_ID |
| Sub ID (sub) | 项目ID | YOUR_PROJECT_ID |
| Ed25519 私钥 | 私钥的 BASE64 编码 | 见下方说明 |
4.2 API Host 选择
- 开发环境：
devapi.qweather.com - 生产环境：如果你在和风天气控制台绑定了自己的域名，填写你的域名
4.3 私钥 BASE64 编码
网站需要的是私钥的 BASE64 编码格式（不包括 PEM 头尾）。
获取方法：
# 方法1：直接查看
grep -v "BEGIN\|END" ed25519-private.pem | tr -d '\n'
# 方法2：手动提取
# 复制私钥内容，去掉 -----BEGIN PRIVATE KEY----- 和 -----END PRIVATE KEY-----
# 然后把多行合并成一行示例输出：
MC4CAQAwBQYDK2VwBCIEIPxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx4.4 完整配置示例
API Host: devapi.qweather.com
Key ID: YOUR_KEY_ID
Sub ID: YOUR_PROJECT_ID
Ed25519 私钥: YOUR_PRIVATE_KEY_BASE64常见问题
Q1: 为什么提示认证失败？
可能原因：
- 私钥格式不正确（确保是 BASE64 编码，不包括 PEM 头尾）
- 凭据ID或项目ID填写错误
- 系统时间不正确（JWT 验证需要准确的时间）
Q2: SHA-256 验证不通过怎么办？
和风天气控制台显示的 SHA-256 是对公钥内容（不包括 PEM 头尾）计算的。如果验证不通过，请确认公钥上传完整。
Q3: 私钥泄露了怎么办？
- 立即在和风天气控制台删除该凭据
- 重新生成密钥对
- 重新创建凭据并配置
Q4: JWT 有效期是多久？
JWT 有效期最长为 24 小时（86400 秒）。网站后台会自动生成新的 JWT，无需手动刷新。
Q5: 可以使用 API KEY 吗？
可以，但 API KEY 安全性较低。从 2027 年 1 月 1 日起，使用 API KEY 的每日请求数量将受到限制。建议使用 JWT 认证。
附录：密钥安全建议
- 私钥保管：私钥文件请妥善保管，不要上传到公开仓库
- 定期更换：建议定期更换密钥对
- 权限控制：私钥文件应设置为仅所有者可读（chmod 600）
- 备份：将私钥备份到安全位置
参考资料
- 和风天气官方文档 - 身份认证
- 和风天气控制台
- JWT.io - JWT 调试工具