Skip to content

World's first open-source enterprise world model.

Deployment defaults stop asking the operator to remember things (#57)

WaylandYangb5b80f94996b
diff --git a/.env.example b/.env.example
index 724320e1..7d2c5304 100644
--- a/.env.example
+++ b/.env.example
@@ -1,12 +1,16 @@
# 复制为 .env 后按需修改。所有配置走 UTOPIA_ 前缀的环境变量。
-UTOPIA_DATABASE_URL=postgres://utopia:utopia@localhost:5432/utopia
+UTOPIA_DATABASE_URL=postgres://utopia:utopia@localhost:1517/utopia
UTOPIA_BIND_ADDR=0.0.0.0:1516
-# 生产环境必须改成随机长密钥
-UTOPIA_JWT_SECRET=dev-secret-change-me
+# JWT 签名密钥。留空即可——首次启动会自动生成一条存进数据库。
+# 只有轮换密钥、或要让多个实例显式对齐时才需要填。
+# UTOPIA_JWT_SECRET=
# 前端构建产物目录(存在则由服务端托管 SPA)
UTOPIA_WEB_DIST=web/dist
# 数据目录:原始文件(files/)与全文索引(index/)
UTOPIA_DATA_DIR=data
+# 强制给会话 cookie 打 Secure。留空即可——走 TLS 时按 X-Forwarded-Proto 自动判定。
+# 只有反向代理不发那个头时才需要打开。
+# UTOPIA_COOKIE_SECURE=true
# 开放注册;false 时仅首个用户可注册,其余由管理员开放
UTOPIA_OPEN_REGISTRATION=true
# 数据库连接池上限。缺省 32,与 worker 并发的缺省对齐。
@@ -18,7 +22,7 @@ UTOPIA_OPEN_REGISTRATION=true
# 数据库口令。默认值只适合本机开发,公开部署务必改。
# UTOPIA_DB_PASSWORD=utopia
# 数据库端口映射。默认只绑回环,仅供本地开发连接;宿主机端口被占时改这里。
-# UTOPIA_DB_BIND=127.0.0.1:5432
+# UTOPIA_DB_BIND=127.0.0.1:1517
# 拉不动 Docker Hub 时,换成任何带 pgvector 的 PG16+ 镜像
# UTOPIA_DB_IMAGE=pgvector/pgvector:pg16
# 部署指定版本,默认 latest
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index ed4627c4..ea69287f 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -66,9 +66,10 @@ jobs:
if docker exec pg pg_isready -U utopia -d utopia >/dev/null 2>&1; then break; fi
sleep 2
done
+ # 故意不给 UTOPIA_JWT_SECRET:让这一跑覆盖自动生成那条路径。
+ # 下面的注册请求会签发并携带 token,密钥没生成好就过不了。
docker run -d --name app --network smoke -p 1516:1516 \
-e UTOPIA_DATABASE_URL=postgres://utopia:utopia@pg:5432/utopia \
- -e UTOPIA_JWT_SECRET=smoke-test-secret \
utopia:smoke
# 必须打 /api/v1/health 并核对 JSON:健康检查挂在 nest("/api/v1") 里,
diff --git a/README.md b/README.md
index e9603fcc..1fe28042 100644
--- a/README.md
+++ b/README.md
@@ -76,9 +76,9 @@ Everything is an environment variable prefixed with `UTOPIA_`; copy [.env.exampl
| Variable | Default | Purpose |
|---|---|---|
-| `UTOPIA_DATABASE_URL` | `postgres://utopia:utopia@localhost:5432/utopia` | Postgres connection string |
+| `UTOPIA_DATABASE_URL` | `postgres://utopia:utopia@localhost:1517/utopia` | Postgres connection string |
| `UTOPIA_BIND_ADDR` | `0.0.0.0:1516` | Listen address |
-| `UTOPIA_JWT_SECRET` | `dev-secret-change-me` | **Change this in production** |
+| `UTOPIA_JWT_SECRET` | _auto-generated_ | Leave unset; generated on first start and stored in the database |
| `UTOPIA_WEB_DIST` | `web/dist` | Built frontend; served as an SPA when present |
| `UTOPIA_DATA_DIR` | `data` | Original files and the full-text index |
| `UTOPIA_OPEN_REGISTRATION` | `true` | When false, only the first account may self-register |
diff --git a/crates/utopia-core/src/config.rs b/crates/utopia-core/src/config.rs
index 770abd9e..c3e225d0 100644
--- a/crates/utopia-core/src/config.rs
+++ b/crates/utopia-core/src/config.rs
@@ -14,7 +14,10 @@ pub struct AppConfig {
/// 不设则回落到 `database_url`:既有部署无需改动即可照常升级。
pub migration_url: Option<String>,
pub bind_addr: String,
- pub jwt_secret: String,
+ /// JWT 签名密钥。留空则首次启动时自动生成并存进 deployment_settings——
+ /// 要求部署者手填一个随机串,现实中的结果是默认值原样上生产。
+ /// 显式给出时优先于库里那条:密钥轮换与多实例显式对齐走这条路。
+ pub jwt_secret: Option<String>,
/// 前端构建产物目录;存在时由服务端托管 SPA(history fallback)。
pub web_dist: String,
/// 数据目录:原始文件(files/)与 Tantivy 索引(index/)。
@@ -22,6 +25,9 @@ pub struct AppConfig {
/// 数据库连接池上限。缺省 32,与 worker 并发的缺省对齐——池子小于并发时
/// 症状是请求变慢而不是任何一处说"池子不够",所以它必须可调。
pub db_max_connections: Option<u32>,
+ /// 强制给会话 cookie 打 Secure。缺省 false:由请求的 X-Forwarded-Proto 判定,
+ /// 走 TLS 才打。只有代理不发那个头时才需要在这里强制打开。
+ pub cookie_secure: bool,
/// 是否开放注册。false 时仅首个用户(引导部署)可注册,其余需管理员开放。
pub open_registration: bool,
}
@@ -29,13 +35,14 @@ pub struct AppConfig {
impl Default for AppConfig {
fn default() -> Self {
Self {
- database_url: "postgres://utopia:utopia@localhost:5432/utopia".into(),
+ database_url: "postgres://utopia:utopia@localhost:1517/utopia".into(),
migration_url: None,
bind_addr: "0.0.0.0:1516".into(),
- jwt_secret: "dev-secret-change-me".into(),
+ jwt_secret: None,
web_dist: "web/dist".into(),
data_dir: "data".into(),
db_max_connections: None,
+ cookie_secure: false,
open_registration: true,
}
}
diff --git a/crates/utopia-server/src/api/auth_routes.rs b/crates/utopia-server/src/api/auth_routes.rs
index b5c3e806..2abf933c 100644
--- a/crates/utopia-server/src/api/auth_routes.rs
+++ b/crates/utopia-server/src/api/auth_routes.rs
@@ -1,6 +1,7 @@
use axum::extract::State;
+use axum::http::HeaderMap;
use axum::Json;
-use axum_extra::extract::cookie::{Cookie, CookieJar};
+use axum_extra::extract::cookie::CookieJar;
use serde::Deserialize;
use serde_json::json;
use utopia_core::models::{User, Workspace};
@@ -43,6 +44,7 @@ fn validate_register(req: &RegisterReq) -> Result<(), AppError> {
pub async fn register(
State(state): State<AppState>,
+ headers: HeaderMap,
jar: CookieJar,
Json(req): Json<RegisterReq>,
) -> ApiResult<(CookieJar, Json<serde_json::Value>)> {
@@ -69,7 +71,8 @@ pub async fn register(
.await?;
let token = auth::issue_token(&state, user.id)?;
- let jar = jar.add(auth::auth_cookie(token.clone()));
+ let secure = auth::behind_tls(&headers, state.cookie_secure);
+ let jar = jar.add(auth::auth_cookie(token.clone(), secure));
let _ = utopia_store::audit::record(
&state.pool,
None,
@@ -105,6 +108,7 @@ async fn record_login_failure(state: &AppState, email: &str, reason: &str) {
pub async fn login(
State(state): State<AppState>,
+ headers: HeaderMap,
jar: CookieJar,
Json(req): Json<LoginReq>,
) -> ApiResult<(CookieJar, Json<serde_json::Value>)> {
@@ -118,7 +122,8 @@ pub async fn login(
return Err(AppError::Unauthorized.into());
}
let token = auth::issue_token(&state, user.id)?;
- let jar = jar.add(auth::auth_cookie(token.clone()));
+ let secure = auth::behind_tls(&headers, state.cookie_secure);
+ let jar = jar.add(auth::auth_cookie(token.clone(), secure));
let _ = utopia_store::audit::record(
&state.pool,
None,
@@ -136,6 +141,7 @@ pub async fn login(
/// 死会话上。所以这里自己解 token 取身份,解不出就只清 cookie 不留痕。
pub async fn logout(
State(state): State<AppState>,
+ headers: HeaderMap,
jar: CookieJar,
) -> (CookieJar, Json<serde_json::Value>) {
if let Some(user_id) = jar
@@ -153,7 +159,8 @@ pub async fn logout(
)
.await;
}
- let jar = jar.remove(Cookie::from(auth::COOKIE_NAME));
+ let secure = auth::behind_tls(&headers, state.cookie_secure);
+ let jar = jar.remove(auth::clear_auth_cookie(secure));
(jar, Json(json!({ "ok": true })))
}
diff --git a/crates/utopia-server/src/auth.rs b/crates/utopia-server/src/auth.rs
index 7776f347..6dc83467 100644
--- a/crates/utopia-server/src/auth.rs
+++ b/crates/utopia-server/src/auth.rs
@@ -57,10 +57,42 @@ pub fn issue_token(state: &AppState, user_id: Uuid) -> Result<String, AppError>
.map_err(|e| AppError::Other(anyhow::anyhow!("Token issuance failed: {e}")))
}
-pub fn auth_cookie(token: String) -> Cookie<'static> {
+/// 外层是否在跑 TLS。反代都会带 `X-Forwarded-Proto`;没有这个头(本地直连、
+/// 开发环境)就当明文,Secure 不打,登录照常工作。
+///
+/// 不需要「信任的代理」名单:伪造这个头只会让攻击者自己的 cookie 变成 Secure,
+/// 更严格而不是更宽松,没有攻击价值。`UTOPIA_COOKIE_SECURE=true` 可强制打开,
+/// 给那些不发这个头的代理兜底。
+pub fn behind_tls(headers: &axum::http::HeaderMap, forced: bool) -> bool {
+ forced
+ || headers
+ .get("x-forwarded-proto")
+ .and_then(|v| v.to_str().ok())
+ // 经过多层代理时这个头是逗号分隔的链,最左边是最初那一跳
+ .and_then(|v| v.split(',').next())
+ .is_some_and(|p| p.trim().eq_ignore_ascii_case("https"))
+}
+
+/// 会话 cookie。`secure` 由 [`behind_tls`] 判定——HTTPS 下打上 Secure,
+/// 浏览器就不会再把它经明文链路发出去。
+pub fn auth_cookie(token: String, secure: bool) -> Cookie<'static> {
Cookie::build((COOKIE_NAME, token))
.path("/")
.http_only(true)
+ .secure(secure)
+ .same_site(SameSite::Lax)
+ .build()
+}
+
+/// 注销用的删除指令。**属性必须和签发时一致**:浏览器按 name + domain + path
+/// 匹配才认得出要删哪一条,只给名字的话 path 会退化成当前请求路径
+/// (`/api/v1/auth`),和签发时的 `/` 对不上——cookie 留在浏览器里,人以为
+/// 自己登出了。
+pub fn clear_auth_cookie(secure: bool) -> Cookie<'static> {
+ Cookie::build((COOKIE_NAME, ""))
+ .path("/")
+ .http_only(true)
+ .secure(secure)
.same_site(SameSite::Lax)
.build()
}
@@ -107,6 +139,18 @@ impl FromRequestParts<AppState> for AuthUser {
}
}
+/// 生成一条 JWT 签名密钥:32 字节 CSPRNG,hex 编码成 64 个字符。
+///
+/// 长度取 32 字节是因为 HS256 的 HMAC 块就是 32 字节——再长会被先哈希一遍,
+/// 并不增加强度。hex 而非 base64:这个值会出现在日志、环境变量和运维的复制粘贴里,
+/// 不带 +/= 省去一整类转义问题。
+pub fn generate_jwt_secret() -> String {
+ use argon2::password_hash::rand_core::RngCore;
+ let mut buf = [0u8; 32];
+ OsRng.fill_bytes(&mut buf);
+ buf.iter().map(|b| format!("{b:02x}")).collect()
+}
+
#[cfg(test)]
mod tests {
use super::*;
@@ -166,4 +210,33 @@ mod tests {
"exp must be enforced by default"
);
}
+
+ fn headers_with(proto: Option<&str>) -> axum::http::HeaderMap {
+ let mut h = axum::http::HeaderMap::new();
+ if let Some(p) = proto {
+ h.insert("x-forwarded-proto", p.parse().unwrap());
+ }
+ h
+ }
+
+ /// Secure 的判定必须只在确认走了 TLS 时为真:判错成 true,明文部署的用户
+ /// 登录后浏览器直接丢掉 cookie,症状是「点了登录又回到登录页」,且不报错。
+ #[test]
+ fn secure_only_when_tls_is_actually_in_front() {
+ // 没有代理:本地直连、cargo run —— 不能打 Secure,否则 HTTP 下登不上
+ assert!(!behind_tls(&headers_with(None), false));
+ assert!(!behind_tls(&headers_with(Some("http")), false));
+
+ assert!(behind_tls(&headers_with(Some("https")), false));
+ // 头的大小写由代理决定,不能假设
+ assert!(behind_tls(&headers_with(Some("HTTPS")), false));
+
+ // 多层代理时这个头是逗号分隔的链,最左边是最初那一跳——
+ // 取错一端会把「用户走 HTTPS 到边缘、边缘走 HTTP 回源」判成明文
+ assert!(behind_tls(&headers_with(Some("https, http")), false));
+ assert!(!behind_tls(&headers_with(Some("http, https")), false));
+
+ // 配置强制打开:给不发这个头的代理兜底
+ assert!(behind_tls(&headers_with(None), true));
+ }
}
diff --git a/crates/utopia-server/src/main.rs b/crates/utopia-server/src/main.rs
index e017e0a0..62fa4f71 100644
--- a/crates/utopia-server/src/main.rs
+++ b/crates/utopia-server/src/main.rs
@@ -64,7 +64,23 @@ async fn main() -> anyhow::Result<()> {
let search = Arc::new(SearchIndex::open(&index_dir)?);
tracing::info!("全文索引就绪: {}", index_dir.display());
- let state = AppState::new(pool.clone(), &cfg, search);
+ // JWT 密钥:环境变量优先(轮换、多实例显式对齐走这条),否则用库里那条;
+ // 库里也没有就现生成一条存进去。生成放在这里而不是 store 里,是因为
+ // OsRng 已经随 argon2 在 server 的依赖里,store 不必为此多一个依赖。
+ // 空串按未设置处理:compose 里写 ${UTOPIA_JWT_SECRET:-} 时环境变量是存在但为空的,
+ // 照字面读会得到 Some("")——一个所有部署都相同的空密钥,比默认值更糟。
+ let jwt_secret = match cfg.jwt_secret.clone().filter(|s| !s.trim().is_empty()) {
+ Some(s) => s,
+ None => {
+ let secret =
+ utopia_store::access::ensure_jwt_secret(&pool, &auth::generate_jwt_secret())
+ .await?;
+ tracing::info!("JWT 密钥取自部署设置(未显式配置 UTOPIA_JWT_SECRET)");
+ secret
+ }
+ };
+
+ let state = AppState::new(pool.clone(), &cfg, search, jwt_secret);
// worker 并发数:系统设置持久化,启动时装载;运行中经同一 AtomicUsize 热调
let n = utopia_store::access::worker_concurrency(&pool)
diff --git a/crates/utopia-server/src/state.rs b/crates/utopia-server/src/state.rs
index 370f804e..94fde742 100644
--- a/crates/utopia-server/src/state.rs
+++ b/crates/utopia-server/src/state.rs
@@ -25,6 +25,8 @@ pub struct AppState {
/// 原始文件字节的存取接缝(内容寻址,key = sha256);当前实现为本地磁盘
pub blob: Arc<dyn crate::blob::BlobStore>,
pub open_registration: bool,
+ /// 强制 Secure cookie(配置项);未强制时按请求的 X-Forwarded-Proto 逐次判定
+ pub cookie_secure: bool,
/// worker 并发数:调度循环每轮热读——系统设置改动即时生效
pub worker_concurrency: Arc<std::sync::atomic::AtomicUsize>,
/// 按模型的并发闸门:后台任务调 LLM 前取许可。限额存库,改完即时生效
@@ -33,17 +35,25 @@ pub struct AppState {
}
impl AppState {
- pub fn new(pool: PgPool, cfg: &AppConfig, search: Arc<SearchIndex>) -> Self {
+ /// `jwt_secret` 由入口解析:环境变量给了就是它,否则是库里那条(首启时生成)。
+ /// 不从 cfg 里取,是因为到这一步它必须已经是确定的一个值,而不是 Option。
+ pub fn new(
+ pool: PgPool,
+ cfg: &AppConfig,
+ search: Arc<SearchIndex>,
+ jwt_secret: String,
+ ) -> Self {
let (events, _) = broadcast::channel(256);
let data_dir = PathBuf::from(&cfg.data_dir);
let blob = Arc::new(crate::blob::LocalBlobStore::new(data_dir.join("files")));
Self {
pool,
- jwt_secret: cfg.jwt_secret.clone(),
+ jwt_secret,
search,
docs: Arc::new(crate::docs_corpus::build_index()),
blob,
open_registration: cfg.open_registration,
+ cookie_secure: cfg.cookie_secure,
worker_concurrency: Arc::new(std::sync::atomic::AtomicUsize::new(32)),
model_gates: Arc::new(crate::llm_util::ModelGates::default()),
events,
diff --git a/crates/utopia-store/src/access.rs b/crates/utopia-store/src/access.rs
index 603fc03c..e6d62b00 100644
--- a/crates/utopia-store/src/access.rs
+++ b/crates/utopia-store/src/access.rs
@@ -172,3 +172,24 @@ pub async fn set_worker_concurrency(pool: &PgPool, value: i32) -> AppResult<()>
.await?;
Ok(())
}
+
+/// 落库自动生成的 JWT 密钥,返回最终生效的那一个。
+///
+/// `COALESCE` 让并发启动的多个实例收敛到同一个值:谁先写谁赢,后来者拿回的是
+/// 库里已有的那条而不是自己刚生成的。分成「先读、没有再写」两步做不到这一点——
+/// 两个实例会同时读到 NULL,各写各的,先写的那个从此在用一个已经不在库里的密钥,
+/// 它签发的 token 到另一个实例上全部失效。
+pub async fn ensure_jwt_secret(pool: &PgPool, generated: &str) -> AppResult<String> {
+ let (secret,): (Option<String>,) = sqlx::query_as(
+ "UPDATE deployment_settings SET jwt_secret = COALESCE(jwt_secret, $1)
+ RETURNING jwt_secret",
+ )
+ .bind(generated)
+ .fetch_one(pool)
+ .await?;
+ secret.ok_or_else(|| {
+ AppError::Other(anyhow::anyhow!(
+ "deployment_settings 没有单例行,JWT 密钥无处落库"
+ ))
+ })
+}
diff --git a/docker-compose.yml b/docker-compose.yml
index adb747a7..865460b4 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -9,10 +9,13 @@ services:
# 应用运行时用的受限角色口令。设了才建角色,不设则应用仍以 owner 身份跑。
UTOPIA_APP_DB_PASSWORD: ${UTOPIA_APP_DB_PASSWORD:-}
ports:
- # 只绑回环。app 走 compose 网络连库,这个映射纯粹是给本地开发用的
- # (cargo run 时从宿主机连)——绑 0.0.0.0 等于把一个默认口令的数据库
- # 挂到公网。宿主机端口被占时用 UTOPIA_DB_BIND 覆盖,如 127.0.0.1:15432。
- - "${UTOPIA_DB_BIND:-127.0.0.1:5432}:5432"
+ # 宿主机侧避开 5432:开发机上常有本地装的 PG 占着那个端口,撞上就是
+ # 起不来。而且撞端口的人恰恰用不了自己那个 PG——它多半没有 pgvector。
+ # 容器内仍是 5432(PG 标准,app 走 compose 网络连的就是它)。
+ #
+ # 只绑回环:这个映射纯粹是给本地开发用的(cargo run 时从宿主机连),
+ # 绑 0.0.0.0 等于把一个默认口令的数据库挂到公网。
+ - "${UTOPIA_DB_BIND:-127.0.0.1:1517}:5432"
volumes:
- dbdata:/var/lib/postgresql/data
# 首次初始化时建受限角色;数据目录已存在的部署不会执行,需手动建一次
@@ -42,7 +45,9 @@ services:
UTOPIA_DATABASE_URL: ${UTOPIA_DATABASE_URL:-postgres://utopia:${UTOPIA_DB_PASSWORD:-utopia}@db:5432/utopia}
UTOPIA_MIGRATION_URL: ${UTOPIA_MIGRATION_URL:-}
UTOPIA_BIND_ADDR: 0.0.0.0:1516
- UTOPIA_JWT_SECRET: ${UTOPIA_JWT_SECRET:-please-change-me-in-production}
+ # 留空:首次启动自动生成一条存进 deployment_settings。这里若给缺省值,
+ # 自动生成就永远走不到,所有部署又会共用同一个人人皆知的密钥。
+ UTOPIA_JWT_SECRET: ${UTOPIA_JWT_SECRET:-}
UTOPIA_WEB_DIST: /app/web-dist
UTOPIA_DATA_DIR: /app/data
# 连接池上限。缺省 32,与 worker 并发的缺省对齐;池子小于并发时症状是
diff --git a/migrations/0033_auto_jwt_secret.sql b/migrations/0033_auto_jwt_secret.sql
new file mode 100644
index 00000000..647b7d13
--- /dev/null
+++ b/migrations/0033_auto_jwt_secret.sql
@@ -0,0 +1,7 @@
+-- JWT 签名密钥不再要求部署者手填。首次启动时自动生成一条存这里,
+-- 于是「照 README 跑起来」和「安全」不再是两件要分别做的事——
+-- 默认值 dev-secret-change-me 上生产这类事故,靠提醒是防不住的。
+--
+-- UTOPIA_JWT_SECRET 仍然优先于本列:轮换密钥、或者要多个实例显式对齐时,
+-- 填环境变量即可,那条路没有被关掉。
+ALTER TABLE deployment_settings ADD COLUMN jwt_secret TEXT;
diff --git a/scripts/e2e_type_drift.sh b/scripts/e2e_type_drift.sh
index a17cdd2b..f915604b 100644
--- a/scripts/e2e_type_drift.sh
+++ b/scripts/e2e_type_drift.sh
@@ -18,7 +18,7 @@ echo "--- 构建 utopia-server"
cargo build -p utopia-server
echo "--- 启动 server (127.0.0.1:$PORT, db=$DB_NAME)"
-UTOPIA_DATABASE_URL="postgres://utopia:utopia@localhost:5432/$DB_NAME" \
+UTOPIA_DATABASE_URL="postgres://utopia:utopia@localhost:1517/$DB_NAME" \
UTOPIA_BIND_ADDR="127.0.0.1:$PORT" \
UTOPIA_DATA_DIR="$DATA_DIR" \
./target/debug/utopia-server &