World's first open-source enterprise world model.
Rust agent-memorybitemporalgraphragknowledge-baseknowledge-graphllmontologypgvectorpostgresqlragrustself-hostedsemantic-searchtemporal-knowledge-graphworld-model
Deployment defaults stop asking the operator to remember things (#57)
WaylandYangb5b80f94996b
diff --git a/.env.example b/.env.exampleindex 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/utopiaUTOPIA_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# 部署指定版本,默认 latestdiff --git a/.github/workflows/release.yml b/.github/workflows/release.ymlindex 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; fisleep 2done+ # 故意不给 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.mdindex 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.rsindex 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.rsindex 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.rsindex 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.rsindex 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.rsindex 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.rsindex 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.ymlindex 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-distUTOPIA_DATA_DIR: /app/data# 连接池上限。缺省 32,与 worker 并发的缺省对齐;池子小于并发时症状是diff --git a/migrations/0033_auto_jwt_secret.sql b/migrations/0033_auto_jwt_secret.sqlnew file mode 100644index 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.shindex 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-serverecho "--- 启动 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 &