外观
和风天气 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 调试工具
