fix(embed): warn at startup when no signing key is configured

Deployments upgraded from the old .env.example keep the published example
SYSTEM_AES_KEY, which SystemHMACKey rejects since v0.8.2. Embed sessions
then fail at request time with no hint at boot.

- Log a [startup-env] warning when no usable signing key is found, and
  surface SYSTEM_SIGNING_KEY in the startup env banner.
- Name SYSTEM_SIGNING_KEY in the embed session 503 error.
- Provision the desktop signing key before printing the banner so the
  desktop build does not warn about a key it is about to create.
- Document the symptoms and fix in troubleshooting.
main
wizardchen 2026-09-24 20:13:46 +08:00 committed by lyingbug
parent 65d8129cb6
commit 3cf0be2e97
4 changed files with 18 additions and 4 deletions

View File

@ -188,11 +188,12 @@ func main() {
// Mute Gin's per-route registration spam; replaced by a single
// summary printed after router build.
runtime.SilenceGinRouteSpam()
runtime.LogStartupEnv(context.Background())
// Provision the signing key first so the startup banner reflects it
// instead of warning about a key the desktop is about to create.
if err := ensureDesktopSigningKey(); err != nil {
panic(fmt.Sprintf("initialize desktop signing key: %v", err))
}
runtime.LogStartupEnv(context.Background())
// Build dependency injection container
c := container.BuildContainer(runtime.GetContainer())

View File

@ -394,7 +394,9 @@ func (h *EmbedChannelHandler) GetEmbedSuggestedQuestions(c *gin.Context) {
func (h *EmbedChannelHandler) CreateEmbedSession(c *gin.Context) {
if len(secutils.SystemHMACKey()) == 0 {
c.JSON(http.StatusServiceUnavailable, gin.H{"error": "embed session signing key is not configured"})
c.JSON(http.StatusServiceUnavailable, gin.H{
"error": "embed session signing key is not configured: set SYSTEM_SIGNING_KEY on the server",
})
return
}
ctx := c.Request.Context()

View File

@ -11,6 +11,7 @@ import (
"github.com/gin-gonic/gin"
"github.com/Tencent/WeKnora/internal/logger"
"github.com/Tencent/WeKnora/internal/utils"
)
// SilenceGinRouteSpam mutes Gin's per-route "[GIN-debug] METHOD path -->
@ -74,6 +75,7 @@ type envVarSpec struct {
var startupEnvVars = []envVarSpec{
// Security
{name: "SYSTEM_AES_KEY", sensitive: true},
{name: "SYSTEM_SIGNING_KEY", sensitive: true},
{name: "JWT_SECRET", sensitive: true},
// Runtime
{name: "GIN_MODE"},
@ -139,6 +141,15 @@ func LogStartupEnv(ctx context.Context) {
"[startup-env] SYSTEM_AES_KEY is set but %d bytes long; AES-256 requires exactly 32 bytes — encryption is DISABLED",
len(k))
}
// Upgrades from example configs keep the published example AES key,
// which SystemHMACKey rejects — embed sessions and presigned links then
// fail at request time with no hint at boot.
if len(utils.SystemHMACKey()) == 0 {
logger.Warn(ctx,
"[startup-env] no usable signing key: set SYSTEM_SIGNING_KEY (e.g. `openssl rand -hex 32`) — "+
"embed sessions and presigned file links are DISABLED. SYSTEM_AES_KEY is only used as a fallback "+
"when it is at least 16 chars and not an example value; do not change it to fix this")
}
if strings.EqualFold(strings.TrimSpace(os.Getenv("REDIS_TLS_INSECURE_SKIP_VERIFY")), "true") {
logger.Warn(ctx,
"[startup-env] REDIS_TLS_INSECURE_SKIP_VERIFY=true — Redis TLS certificate verification is DISABLED; do not use in production")

View File

@ -24,7 +24,7 @@ docker compose logs --tail=200 postgres redis
| 报错提示「仅允许白名单出站」 | 部署开启了 `SSRF_DNS_WHITELIST_ONLY`,不在白名单的主机在 DNS 解析前即被拒绝。把目标主机加入 `SSRF_WHITELIST` 或 `SSRF_WHITELIST_EXTRA` 后重建 app / docreader 容器,见[配置详解](04-configuration.md) |
| 登录接口返回 HTML 404 | 检查 `SEARXNG_PORT` 是否与 `APP_PORT`(默认 8080)相同。Linux 上 SearXNG 绑定 `127.0.0.1:8080` 后,`localhost:8080` 的请求会先到 SearXNG。保持 SearXNG 使用 8888 或其他空闲端口 |
| 拉取 MinIO 镜像提示 `pull access denied` | MinIO 已不再向 Docker Hub 发布镜像。当前 Compose 与 Helm 使用 `quay.io/minio/minio`;自定义编排文件需同步修改镜像地址 |
| 升级后嵌入页面或签名链接失效 | 签名密钥取 `SYSTEM_SIGNING_KEY`,未设置时回退到 `SYSTEM_AES_KEY`;示例密钥和长度不足 16 的密钥不能签名。v0.8.2 更换了嵌入会话的签名算法,升级前签发的嵌入会话全部失效,访客需重新进入;多副本部署须使用同一个密钥 |
| 升级后嵌入页面或签名链接失效(嵌入页提示 `embed session signing key is not configured`,启动日志有 `[startup-env] no usable signing key`) | 签名密钥取 `SYSTEM_SIGNING_KEY`,未设置时回退到 `SYSTEM_AES_KEY`;示例密钥和长度不足 16 的密钥不能签名。用 `openssl rand -hex 32` 生成并配置 `SYSTEM_SIGNING_KEY` 即可,**不要为此修改 `SYSTEM_AES_KEY`**,否则已保存的凭据无法解密。v0.8.2 更换了嵌入会话的签名算法,升级前签发的嵌入会话全部失效,访客需重新进入;多副本部署须使用同一个密钥 |
| 升级后钉钉机器人不再回复 | v0.8.2 起钉钉只支持 Stream 模式,升级迁移会把 `webhook` 渠道改为 `websocket`。需在钉钉开发者后台为该应用开启 Stream 模式,见[IM 集成](../03-features/12-im-integration.md) |
| 后台队列持续积压 | 结合最老任务等待时间、活跃 worker 和下游配额定位;提高 worker 数不会增加模型供应商配额,见[容量估算](../02-architecture/05-async-tasks.md#capacity-planning) |
| 技能已加入目录却不可执行 | 目录收录和沙箱安装是两步;检查安装记录、智能体的沙箱选择与技能范围,见[技能目录与沙箱](../03-features/22-skills-sandbox.md) |