服务器配置
环境变量、认证、缓存、存储，以及运行时设置保存在哪里。
了解哪些设置应该写在 .env 中、哪些保存在数据库里，每个环境变量的作用是什么，以及服务器行为异常时应该先检查哪里。每个运行时设置及其默认值，列在设置项参考中。
两类设置
| 类别 | 存放位置 | 示例 | 修改方式 |
|---|---|---|---|
| 部署设置 | docker-compose.yml 旁的 .env，或服务器的环境变量 | 数据库 URL、端口、API_TOKEN、Redis、存储路径、时区 | 编辑 .env，然后运行 docker compose up -d |
| 运行时设置 | Lore 数据库 | Embedding 和 View LLM、召回调优、Dream 和备份的定时任务、提示词 | /setup、/settings 或 PUT /api/settings |
数据库凭据和令牌应保存在 .env 中。模型 key 则在运行时设置中填写。Lore 不会从 .env 读取模型 key。
环境变量
以下变量是官方 docker-compose.yml 读取的变量。.env 中的值会覆盖默认值。
| 变量 | 默认值 | 用途 |
|---|---|---|
TZ | Asia/Shanghai | Web 和 PostgreSQL 容器的时钟与时区。Dream 和备份的定时任务使用它。 |
POSTGRES_DB | lore | 内置 PostgreSQL 容器创建的数据库名。 |
POSTGRES_USER | lore | 内置 PostgreSQL 容器创建的角色。 |
POSTGRES_PASSWORD | change-me | POSTGRES_USER 的密码。CLI 会生成一个随机密码。 |
POSTGRES_PORT | 55439 | 内置 PostgreSQL 的宿主机端口。 |
POSTGRES_DATA_DIR | ./data/postgres | PostgreSQL 数据的宿主机目录。 |
DATABASE_URL | postgresql://lore:change-me@postgres:5432/lore | Web 服务器使用的数据库。如果你自己运行数据库，就把它指向你的数据库。请让它的密码与 POSTGRES_PASSWORD 保持一致。 |
WEB_PORT | 18901 | Web 控制台和 API 的宿主机端口。 |
API_TOKEN | 留空 | Web 与 API 请求必须携带的 Bearer 令牌。留空表示不做身份验证。 |
LORE_DB_POOL_SIZE | 10 | Web 服务器可保持打开的数据库连接数。 |
REDIS_URL | redis://redis:6379/0 | Redis 缓存。未设置，或启动时无法连接，Lore 就使用进程内缓存。 |
REDIS_DATA_DIR | ./data/redis | Redis 数据的宿主机目录。 |
CACHE_KEY_PREFIX | lore | 缓存键的前缀。 |
CACHE_LOCAL_MAX_ITEMS | 2000 | 进程内缓存的最大条目数。 |
SNAPSHOT_DATA_DIR | ./data/snapshots | 备份和待审核变更记录的宿主机目录。 |
LORE_POSTGRES_IMAGE | fffattiger/pgvector-zhparser:pg16 | PostgreSQL 镜像。 |
LORE_REDIS_IMAGE | redis:7-alpine | Redis 镜像。 |
LORE_FRONTEND_IMAGE | fffattiger/lore:latest | Web 服务器镜像。预发布和开发渠道分别使用 pre-latest 和 dev-latest。 |
CLI 会自己写入 .env。它会设置一个随机的 POSTGRES_PASSWORD、与之匹配的 DATABASE_URL、TZ=Asia/Shanghai，以及 ~/.lore/docker/data 下的绝对数据路径。
Redis 与本地缓存
- 设置了
REDIS_URL，且启动时能连通： Lore 使用 Redis 缓存。如果你运行多个 Lore Web 进程，就应该使用 Redis。 - 未设置
REDIS_URL，或启动时无法连接 Redis： Lore 使用进程内存缓存，最多保存CACHE_LOCAL_MAX_ITEMS条。对于单个 Web 进程，这已经够用。 CACHE_KEY_PREFIX： 当 Redis 与其他应用共用时，用它把 Lore 的键与其他键区分开。cache.enabled： 运行时设置，默认开启。设为false后，所有缓存读写都会被跳过。
存储与持久化
| 宿主机路径（默认） | 挂载到容器中的位置 | 内容 |
|---|---|---|
./data/postgres（POSTGRES_DATA_DIR） | /var/lib/postgresql/data | 记忆节点、历史和设置 |
./data/redis（REDIS_DATA_DIR） | /data | 缓存数据，保存在追加写入文件中 |
./data/snapshots（SNAPSHOT_DATA_DIR） | /app/snapshots | 自动备份和待审核的变更记录 |
请把这些目录放在持久化存储上。升级前，请备份 PostgreSQL 和快照目录。参见更新与卸载。
数据库连接池
LORE_DB_POOL_SIZE 设置 Web 服务器最多可以保持打开的 PostgreSQL 连接数，默认为 10。除非你已经测得需要更多连接，否则保持默认值即可。
时区
TZ 设置 Web 和 PostgreSQL 容器的时钟。官方 Compose 文件的默认值是 Asia/Shanghai。Dream 和备份的定时任务都按这个时钟运行，因此默认的 dream.cron 0 3 * * * 会在 Asia/Shanghai 的 03:00 运行。如需修改，请设置 IANA 时区名称，例如 Europe/Berlin，然后运行 docker compose up -d。
运行时设置
运行时设置保存在数据库中。第一次设置时在 /setup 中完成，之后在 /settings 中修改，或者使用 PUT /api/settings。设置项参考列出了每个键的默认值和作用。设置分为以下几组：
- 召回： 显示阈值、条数上限、查询和超时保护、权重、加分和新近度。
- 视图： gist 视图和 question 视图的权重与先验值。
- 模型： embedding 端点和 View LLM。
- 生命周期： 会话启动时服务器注入的使用规则和前言。
- 策略： 优先级容量检查和触发条件检查。
- Dream 和 备份： 定时任务和保留策略。
- 缓存 和 提示词： 缓存开关和提示词模板。
密钥类设置（embedding.api_key、view_llm.api_key 和 backup.webdav.password）只写不读。Lore 只会显示它们是否已设置。
快速排查
| 现象 | 检查什么 | 怎么办 |
|---|---|---|
/api/health 失败 | 运行 docker compose ps 和 docker compose logs web | 等到 postgres 和 redis 都健康。确认 DATABASE_URL 与数据库设置一致。 |
修改 POSTGRES_PASSWORD 后，Web 容器无法连接 PostgreSQL | PostgreSQL 只在创建数据目录时读取该变量 | 在 PostgreSQL 中用 ALTER ROLE 修改该角色的密码，然后更新 DATABASE_URL 使其一致。 |
| 中文查询匹配效果差 | 在 psql 中运行 \dx，查看是否有 pg_jieba 或 zhparser | 安装并预加载 pg_jieba。参见使用自己的 PostgreSQL。 |
| 召回结果为空 | 打开 /recall，查看候选结果和分数 | 检查 embedding 设置，然后检查 recall.display.min_display_score。参见提升召回质量。 |
| Dream 从不运行 | dream.enabled 为 true，且已设置 view_llm.base_url | 配置 View LLM。检查 TZ 和 dream.cron。 |
| 没有生成备份文件 | backup.enabled 和 backup.local.enabled 为 true。运行 docker compose exec web ls /app/snapshots。 | 打开相关设置，或修正 SNAPSHOT_DATA_DIR 的挂载。 |
| 客户端被拒绝 | .env 中的 API_TOKEN，以及每个客户端发送的令牌 | 用相同的值，加上 -y --api-token 重新运行安装器，然后重启运行时。参见用 API_TOKEN 保护服务器。 |
| 端口已被占用 | .env 中的 WEB_PORT 或 POSTGRES_PORT | 修改端口，然后运行 docker compose up -d。CLI 的 --docker 健康检查要求端口为 18901。 |
Agent 端的问题，请参阅Agent 接入问题。