Skip to content

docs: clarify supported authentication and deployment storage #34

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
xiaour merged 1 commit into from
Oct 16, 2026
Merged

docs: clarify supported authentication and deployment storage #34

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 4 additions & 3 deletions .env.example
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ USER_MEMORY_MAINTENANCE_STARTUP_DELAY_MS=60000
USER_MEMORY_MAINTENANCE_BATCH_SIZE=20

# ============================================================
# P0 生产化加固（详见 docs/capability-gaps.md）
# 生产化加固与预留配置（当前支持范围见 README.md 的生产化注意事项）
# ============================================================

# P0-2 提示注入清洗：默认开启，上传文件/附件进模型上下文前自动中和注入特征。
Expand All @@ -84,8 +84,9 @@ AUTH_OIDC_CLIENT_ID=
AUTH_OIDC_AUDIENCE=
AUTH_OIDC_JWKS_URI=

# P0-1 外部库与分布式锁（可选）。DATABASE_BACKEND=sqlite 为当前默认；
# 多实例部署需改为外部库（如 postgres）并配置 REDIS_URL 启用真正的分布式会话锁。
# 外部平台库与分布式锁（尚未接入应用启动流程）。以下变量目前不会切换存储或启用锁。
# 平台状态仍保存在 SQLite；业务 PostgreSQL 数据源与平台状态存储是独立能力。
# 当前应按单实例部署；外部平台库和 Redis 锁需要完成应用集成后才能使用。
DATABASE_BACKEND=sqlite
REDIS_URL=

8 changes: 4 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,7 @@ YOLO Data 面向企业，将多年沉淀的数据分析经验与大模型能力
- 通过 Streamable HTTP `/mcp` 暴露 `list_metrics`、`get_policy`、`get_snapshot`、`resolve_query`、`execute_query` 五个工具。
- 查询必须先解析契约再执行；详见 [MCP 连接器](mcp-connector/README.md)。
- **生产化加固**
- 支持提示注入清洗、每日 Token 预算、OIDC/JWT 登录，以及 Docker/Podman + seccomp 代码执行隔离。
- 支持提示注入清洗、每日 Token 预算、会话登录，以及 Docker/Podman + seccomp 代码执行隔离。
- 默认 `inprocess` 仅适合可信环境；多租户部署应配置 `SANDBOX_BACKEND=container` 或 `podman`。

## 业务规则与提示词设置
Expand Down Expand Up @@ -238,13 +238,13 @@ curl -N -X POST http://localhost:8088/api/chat/query/stream \
- 关键操作写入审计日志。
- 上传文件进入模型上下文前默认执行提示注入清洗。
- 可设置每日 Token 上限。
- 生产环境可使用 `AUTH_MODE=oidc` 接入 OIDC/JWT。
- 当前应用支持 `AUTH_MODE=dev` / `session`；对外部署使用 `session`。OIDC/JWT 模块尚未接入应用鉴权流程，`AUTH_MODE=oidc` 会阻止启动。

## 生产化注意事项

- `docker compose up -d` 默认是开发体验配置（`AUTH_MODE=dev`）。对外部署必须改为 `AUTH_MODE=session` 或 `oidc`、修改默认口令，并在 HTTPS 反向代理后运行；`NODE_ENV=production` 下直接用 HTTP 访问会因 Secure Cookie 导致登录失败。
- `docker compose up -d` 默认是开发体验配置（`AUTH_MODE=dev`）。对外部署必须改为 `AUTH_MODE=session`、修改默认口令，并在 HTTPS 反向代理后运行；`NODE_ENV=production` 下直接用 HTTP 访问会因 Secure Cookie 导致登录失败。
- 代码执行默认 `SANDBOX_BACKEND=inprocess`，这不是安全边界。不可信用户场景应配置 Docker/Podman 容器、seccomp、无网络和只读根文件系统。
- SQLite 为单节点存储，多实例部署前应迁移到外部数据库，并配置 Redis 分布式锁。
- 平台状态当前使用 SQLite，应按单实例部署。`DATABASE_BACKEND` 和 `REDIS_URL` 尚未接入应用启动流程，设置它们不会切换平台存储或启用分布式会话锁；多实例部署仍需完成外部平台库和锁的集成。PostgreSQL 业务数据源支持不代表平台状态可存入 PostgreSQL。
- `REFLECTION_ENABLED` 与 `REFLECTION_MAX_REPLAN` 控制执行后反思；`npm run eval` 或 `/api/eval` 可查看 L1/L2/L3 回归评测。

## 相关文档
Expand Down
8 changes: 4 additions & 4 deletions README_EN.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ Enterprise analytics requires more than sending database schemas to an LLM. The
- Exposes `list_metrics`, `get_policy`, `get_snapshot`, `resolve_query`, and `execute_query` over Streamable HTTP at `/mcp`.
- Queries must resolve a contract before execution. See the [MCP connector](mcp-connector/README.md).
- **Production hardening**
- Prompt-injection sanitization, daily token budgets, OIDC/JWT authentication, and Docker/Podman plus seccomp execution isolation.
- Prompt-injection sanitization, daily token budgets, session authentication, and Docker/Podman plus seccomp execution isolation.
- The default `inprocess` backend is suitable only for trusted environments. Multi-tenant deployments should use `SANDBOX_BACKEND=container` or `podman`.

## Business Rules and Prompts
Expand Down Expand Up @@ -203,13 +203,13 @@ curl -N -X POST http://localhost:8088/api/chat/query/stream \
- Critical operations are written to the audit log.
- Uploaded content is sanitized for prompt injection before entering model context.
- Daily token limits can be configured.
- Production deployments can use `AUTH_MODE=oidc` with OIDC/JWT.
- The application supports `AUTH_MODE=dev` / `session`; use `session` for external deployments. The OIDC/JWT module is not integrated into application authentication, and `AUTH_MODE=oidc` prevents startup.

## Production Notes

- `docker compose up -d` defaults to the development-oriented `AUTH_MODE=dev`. External deployments must use `AUTH_MODE=session` or `oidc`, change the default password, and run behind an HTTPS reverse proxy. Direct HTTP access with `NODE_ENV=production` will fail login because Secure cookies are required.
- `docker compose up -d` defaults to the development-oriented `AUTH_MODE=dev`. External deployments must use `AUTH_MODE=session`, change the default password, and run behind an HTTPS reverse proxy. Direct HTTP access with `NODE_ENV=production` will fail login because Secure cookies are required.
- `SANDBOX_BACKEND=inprocess` is not a security boundary. Untrusted environments should use Docker or Podman with seccomp, no network, and a read-only root filesystem.
- SQLite is intended for a single node. Multi-instance deployments should migrate to an external database and configure a Redis distributed lock.
- Platform state currently uses SQLite; deploy a single instance. `DATABASE_BACKEND` and `REDIS_URL` are not wired into application startup, so setting them does not switch platform storage or enable distributed session locks. Multiple instances still require integration of an external platform database and locking. PostgreSQL business-data sources do not provide PostgreSQL storage for platform state.
- `REFLECTION_ENABLED` and `REFLECTION_MAX_REPLAN` control answer reflection. Run `npm run eval` or use `/api/eval` for L1/L2/L3 regression evaluation.

## Documentation
Expand Down
Loading