Self-host Utopia

Utopia README

How to install Utopia

UTOPIA_IMAGE, UTOPIA_DB_PASSWORD, UTOPIA_DB_IMAGE

git clone https://github.com/deeplethe/utopia.git
cd utopia
docker compose --profile app up -d

How to configure Utopia

• UTOPIA_APP_DB_PASSWORD--- 受限数据库角色（可选，推荐新部署启用）--- 不设则应用以数据库 owner 身份运行：那个身份能 DROP TRIGGER，也就能绕过 台账的不可变约束。设了之后应用改用 utopia_app 连库——业务表照常读写， 台账只能写和读，改不动也删不掉；迁移另走 owner 连接，用完即释放。 注意：这一层挡的是应用 bug、SQL 注入与泄漏出去的连接串，挡不住能登进 服务器的人（容器内 psql 免密即 superuser）。那属于服务器访问控制。 首次 up 时由 init 脚本建角色，因此三条要一起给：

  --- 受限数据库角色（可选，推荐新部署启用）--- 不设则应用以数据库 owner 身份运行：那个身份能 DROP TRIGGER，也就能绕过 台账的不可变约束。设了之后应用改用 utopia_app 连库——业务表照常读写， 台账只能写和读，改不动也删不掉；迁移另走 owner 连接，用完即释放。 注意：这一层挡的是应用 bug、SQL 注入与泄漏出去的连接串，挡不住能登进 服务器的人（容器内 psql 免密即 superuser）。那属于服务器访问控制。 首次 up 时由 init 脚本建角色，因此三条要一起给：

• UTOPIA_BIND_ADDR=0.0.0.0:1516
• UTOPIA_COOKIE_SECURE强制给会话 cookie 打 Secure。留空即可——走 TLS 时按 X-Forwarded-Proto 自动判定。 只有反向代理不发那个头时才需要打开。

  强制给会话 cookie 打 Secure。留空即可——走 TLS 时按 X-Forwarded-Proto 自动判定。 只有反向代理不发那个头时才需要打开。

• UTOPIA_DATABASE_URL=postgres://utopia:utopia@localhost:1517/utopia复制为 .env 后按需修改。所有配置走 UTOPIA_ 前缀的环境变量。

  复制为 .env 后按需修改。所有配置走 UTOPIA_ 前缀的环境变量。

• UTOPIA_DATA_DIR=data数据目录：原始文件（files/）与全文索引（index/）

  数据目录：原始文件（files/）与全文索引（index/）

• UTOPIA_DB_BIND数据库端口映射。默认只绑回环，仅供本地开发连接；宿主机端口被占时改这里。

  数据库端口映射。默认只绑回环，仅供本地开发连接；宿主机端口被占时改这里。

• UTOPIA_DB_IMAGE拉不动 Docker Hub 时，换成任何带 pgvector 的 PG16+ 镜像

  拉不动 Docker Hub 时，换成任何带 pgvector 的 PG16+ 镜像

• UTOPIA_DB_MAX_CONNECTIONS数据库连接池上限。缺省 32，与 worker 并发的缺省对齐。 池子小于并发时症状是请求变慢、而不是任何一处说"池子不够"——调高 worker 并发时一并考虑这里，也别超过 Postgres 自己的 max_connections（默认 100）。

  数据库连接池上限。缺省 32，与 worker 并发的缺省对齐。 池子小于并发时症状是请求变慢、而不是任何一处说"池子不够"——调高 worker 并发时一并考虑这里，也别超过 Postgres 自己的 max_connections（默认 100）。

• UTOPIA_DB_PASSWORD--- 以下几项由 docker-compose 读取，不是应用配置 --- 数据库口令。默认值只适合本机开发，公开部署务必改。 只在数据卷首次初始化时写进库；之后再改这里只改了应用这一头，库里那份要用 docker compose exec db psql -U utopia -c "ALTER USER utopia PASSWORD '新口令'" 同步改， 或者 docker compose --profile app down -v 从头来过（会删掉全部数据）。

  --- 以下几项由 docker-compose 读取，不是应用配置 --- 数据库口令。默认值只适合本机开发，公开部署务必改。 只在数据卷首次初始化时写进库；之后再改这里只改了应用这一头，库里那份要用 docker compose exec db psql -U utopia -c "ALTER USER utopia PASSWORD '新口令'" 同步改， 或者 docker compose --profile app down -v 从头来过（会删掉全部数据）。

• UTOPIA_IMAGE部署指定版本，默认 latest

  部署指定版本，默认 latest

• UTOPIA_JWT_SECRETJWT 签名密钥。留空即可——首次启动会自动生成一条存进数据库。 只有轮换密钥、或要让多个实例显式对齐时才需要填。

  JWT 签名密钥。留空即可——首次启动会自动生成一条存进数据库。 只有轮换密钥、或要让多个实例显式对齐时才需要填。

• UTOPIA_MIGRATION_URL
• UTOPIA_OIDC_ALLOWED_DOMAINS这些域名（逗号分隔）里、身份提供方核实过的 email 首次单点登录时：按 email 关联已有账号， 没有就开一个（默认工作区的 viewer，没有密码）。留空 = 只认本人绑定过的身份。 只在身份提供方对这些域名说了算时打开（0069）：普通的 Google client 也会为拿公司邮箱注册的 个人 Google 账号作保，最好前面再挡一层只放行本公司账号的代理。 这份名单不看 UTOPIA_OPEN_REGISTRATION 与管理员的「开放注册」：关着注册照样开户。 停用账号还占着的 email 不会开新号。

  这些域名（逗号分隔）里、身份提供方核实过的 email 首次单点登录时：按 email 关联已有账号， 没有就开一个（默认工作区的 viewer，没有密码）。留空 = 只认本人绑定过的身份。 只在身份提供方对这些域名说了算时打开（0069）：普通的 Google client 也会为拿公司邮箱注册的 个人 Google 账号作保，最好前面再挡一层只放行本公司账号的代理。 这份名单不看 UTOPIA_OPEN_REGISTRATION 与管理员的「开放注册」：关着注册照样开户。 停用账号还占着的 email 不会开新号。

• UTOPIA_OIDC_CLIENT_ID
• UTOPIA_OIDC_CLIENT_SECRET
• UTOPIA_OIDC_EXCHANGE_AUDIENCES受信的另一个应用可以拿它用户在同一个身份提供方刚登录到的 ID token，到 POST /api/v1/auth/oidc/exchange 换一个 Utopia 会话（0066）。这里列它的 client id，逗号分隔； 与 Utopia 共用一个 client 的就写 Utopia 自己的 client id。留空 = 不开放这个端点。 映射与登录相同：本人绑定过的身份；设了 UTOPIA_OIDC_ALLOWED_DOMAINS 时，那些域名里的人 也会像首次登录一样被关联或开户（0069）。每个 ID token 只能换一次。

  受信的另一个应用可以拿它用户在同一个身份提供方刚登录到的 ID token，到 POST /api/v1/auth/oidc/exchange 换一个 Utopia 会话（0066）。这里列它的 client id，逗号分隔； 与 Utopia 共用一个 client 的就写 Utopia 自己的 client id。留空 = 不开放这个端点。 映射与登录相同：本人绑定过的身份；设了 UTOPIA_OIDC_ALLOWED_DOMAINS 时，那些域名里的人 也会像首次登录一样被关联或开户（0069）。每个 ID token 只能换一次。

• UTOPIA_OIDC_ISSUER单点登录（可选）。ISSUER、CLIENT_ID、REDIRECT_URI 三项都填才生效（CLIENT_SECRET 看身份 提供方要不要），留空即关闭——登录页不会露出那个按钮。账号由本人在账户页绑定自己的 身份（先用密码登录再走一遍 SSO；设了 UTOPIA_OIDC_ALLOWED_DOMAINS 则首次登录自动关联）， 这几项只决定拿哪个身份提供方去核验令牌。 本地开发要用 http://localhost 上的身份提供方时，设 UTOPIA_OIDC_ALLOW_LOOPBACK_HTTP=1。

  单点登录（可选）。ISSUER、CLIENT_ID、REDIRECT_URI 三项都填才生效（CLIENT_SECRET 看身份 提供方要不要），留空即关闭——登录页不会露出那个按钮。账号由本人在账户页绑定自己的 身份（先用密码登录再走一遍 SSO；设了 UTOPIA_OIDC_ALLOWED_DOMAINS 则首次登录自动关联）， 这几项只决定拿哪个身份提供方去核验令牌。 本地开发要用 http://localhost 上的身份提供方时，设 UTOPIA_OIDC_ALLOW_LOOPBACK_HTTP=1。

• UTOPIA_OIDC_REDIRECT_URI
• UTOPIA_OPEN_REGISTRATION=true开放注册；false 时仅首个用户可注册，其余由管理员开放

  开放注册；false 时仅首个用户可注册，其余由管理员开放

• UTOPIA_PASSWORD_LOGIN密码登录与注册。false = 只走单点登录（登录页只剩那个按钮）；身份提供方出事时改回 true。 没配单点登录时这个 false 不生效。单点登录开的账号没有密码、也没法重设，改回 true 也进不去—— 包括经 SSO 引导出来的首个管理员。务必留一个有密码的管理员账号当后门。

  密码登录与注册。false = 只走单点登录（登录页只剩那个按钮）；身份提供方出事时改回 true。 没配单点登录时这个 false 不生效。单点登录开的账号没有密码、也没法重设，改回 true 也进不去—— 包括经 SSO 引导出来的首个管理员。务必留一个有密码的管理员账号当后门。

• UTOPIA_SECRET_KEY凭据封印钥匙（LLM API Key、连接串、来源 token 落库前用它加密；32 字节，64 位十六进制或 base64）。 留空即可——首次启动会生成到数据目录的 secret.key。钥匙不进库；备份数据目录时一起带走。

  凭据封印钥匙（LLM API Key、连接串、来源 token 落库前用它加密；32 字节，64 位十六进制或 base64）。 留空即可——首次启动会生成到数据目录的 secret.key。钥匙不进库；备份数据目录时一起带走。

• UTOPIA_WEB_DIST=web/dist前端构建产物目录（存在则由服务端托管 SPA）

  前端构建产物目录（存在则由服务端托管 SPA）