diff --git a/cmd/desktop/main.go b/cmd/desktop/main.go index 3b8e8578..f0b7e640 100644 --- a/cmd/desktop/main.go +++ b/cmd/desktop/main.go @@ -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()) diff --git a/internal/handler/embed_channel.go b/internal/handler/embed_channel.go index 47fdec62..a03fe26b 100644 --- a/internal/handler/embed_channel.go +++ b/internal/handler/embed_channel.go @@ -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() diff --git a/internal/runtime/startup.go b/internal/runtime/startup.go index dc5da747..2c5646fb 100644 --- a/internal/runtime/startup.go +++ b/internal/runtime/startup.go @@ -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") diff --git a/website-docs/01-getting-started/05-troubleshooting.md b/website-docs/01-getting-started/05-troubleshooting.md index eafe3bc1..90f3c56e 100644 --- a/website-docs/01-getting-started/05-troubleshooting.md +++ b/website-docs/01-getting-started/05-troubleshooting.md @@ -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) |