Skip to content

Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.

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

wizardchen3cf0be2e9745
diff --git a/cmd/desktop/main.go b/cmd/desktop/main.go
index 3b8e85785..f0b7e640a 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 47fdec621..a03fe26b7 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 dc5da7471..2c5646fb1 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 eafe3bc1e..90f3c56ed 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) |