freedak/MyAiDesk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
MyAiDesk/nomifun-tauri/docs/reference/configuration.zh.md
T
freedak f7a720204a Update: 将子项目从 submodule 转为完整内容 
- 移除 GovAI, nomifun-tauri, 算力盒子 的 submodule 引用
- 添加所有子项目的完整源代码
- 保留原始 .git 为 .git.bak 备份
2026-07-04 19:20:46 +08:00

195 lines
13 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 配置参考
NomiFun 读取的每一个参数与环境变量、它们的默认值，以及各自归属的文件。
所有取值都直接来自源码——本页没有列出的设置就不存在。
NomiFun 交付的是**一个**统一的 Rust 后端（`nomifun-app`，二进制
`nomicore`），以及两个嵌入它的宿主：
- `nomifun-desktop` —— Tauri 桌面外壳。在选定的 loopback 端口上以
`AuthPolicy::TrustLocalToken` 启动后端，并把每次启动生成的本地信任 secret
注入自己的 WebView。
- `nomifun-web` —— 独立的 Web/服务端宿主。默认以**已鉴权**模式启动同一
个后端，并在同一端口上提供 SPA。
两个宿主共享后端的同一组配置面；各自的 CLI 仅会覆盖它们自己拥有的那几项。
## `nomifun-web` 参数与环境变量
来源：[`apps/web/src/main.rs`](../../apps/web/src/main.rs)。
| 参数 | 环境变量 | 默认值 | 用途 |
|---|---|---|---|
| `--host` | `NOMIFUN_WEB_HOST` | `127.0.0.1` | 绑定的 IP。`0.0.0.0` 会接受 LAN/VPN/公网流量；大范围暴露前请先预置或完成首次设置。不解析主机名；非法输入将在启动阶段直接失败。 |
| `--port` | `NOMIFUN_WEB_PORT` | `8787` | TCP 端口。在同一个 socket 上提供 API、`/ws` WebSocket 与 SPA。 |
| `--data-dir` | `NOMIFUN_DATA_DIR` | 按用户的应用数据目录 | 后端数据目录（SQLite 数据库、智能体状态、日志、Bun 缓存）。默认是所有宿主共享的按用户位置——Windows 上是 `%LOCALAPPDATA%\NomiFun\Nomi`，macOS 上是 `~/Library/Application Support/NomiFun/Nomi`，Linux 上是 `$XDG_DATA_HOME/NomiFun/Nomi`。可用本参数或 `NOMIFUN_DATA_DIR`（按字面值，不附加后缀）覆盖；生产环境请使用绝对路径。 |
| `--dist` | `NOMIFUN_WEB_DIST` | `../../ui/dist` | 已构建 SPA 所在目录。在仓库之外部署时务必显式指定。 |
| `--admin-user` | `NOMIFUN_ADMIN_USERNAME` | `admin` | 预置首位管理员时使用的用户名。管理员存在后将被忽略。 |
| `--admin-password` | `NOMIFUN_ADMIN_PASSWORD` | — | 在启动时预置首位管理员密码，跳过交互式设置。管理员存在后将被忽略。 |
| `--insecure-no-auth` | `NOMIFUN_WEB_INSECURE_NO_AUTH` | `false` | 危险。完全禁用鉴权（桌面式本地模式）。仅可用于 loopback 或完全受信任的私有网络。 |
布尔环境变量接受 `1`、`true`、`yes`、`on`（不区分大小写）。
## `nomicore`（后端）参数
来源：[`crates/backend/nomifun-app/src/cli.rs`](../../crates/backend/nomifun-app/src/cli.rs)。
下面是独立 `nomicore` 二进制对外暴露的参数。两个宿主会构造一个带默认值
的 `Cli`，仅覆盖各自拥有的那部分——所以单独运行后端时这些参数同样适用。
| 参数 | 默认值 | 用途 |
|---|---|---|
| `--host` | `127.0.0.1`（`DEFAULT_HOST`） | 监听的主机地址。 |
| `--port` | `25808`（`DEFAULT_PORT`） | 监听端口。 |
| `--data-dir` | 按用户的应用数据目录 | 数据库 + 文件存储根目录。通过 clap 绑定 `NOMIFUN_DATA_DIR` 环境变量（按字面值）；两者都未设置时解析 `default_data_dir()`——所有宿主共享的那个按用户位置。 |
| `--work-dir` | （无） | 会话工作区目录。回退顺序：`NOMIFUN_WORK_DIR` 环境变量 → 数据目录本身。 |
| `--app-version` | crate 版本 | 报告给扩展引擎用于做兼容性检查的宿主应用版本。 |
| `--local` | `false` | 独立 `nomicore` 的无鉴权本地模式。`nomifun-web --insecure-no-auth` 映射到同一策略。桌面外壳不使用该 flag，而是使用 `TrustLocalToken`。 |
| `--log-dir` | `<data-dir>/logs` | 滚动日志的目录。 |
| `--log-level` | `info` | 日志级别过滤。支持按 target 覆盖——例如 `info,nomifun_mcp=trace`。 |
子命令（供智能体 CLI 桥与诊断使用）：
| 子命令 | 用途 |
|---|---|
| `mcp-requirement-stdio` | AutoWork requirement 声明工具的 MCP stdio server。 |
| `mcp-knowledge-stdio` | 每会话 knowledge search 的 MCP stdio server。 |
| `mcp-gateway-stdio` | Desktop Gateway 工具的 MCP stdio server。 |
| `mcp-open-stdio` | 暴露可靠 OS `open` 工具的 MCP stdio server。 |
| `mcp-computer-stdio` | 暴露 desktop computer-use 工具的 MCP stdio server。 |
| `mcp-browser-stdio` | 暴露 browser-use 工具的 MCP stdio server。 |
| `terminal-hook --event <kind>` | 一次性 terminal 生命周期 hook relay。 |
| `doctor` | 自检：填充智能体注册表，逐个探测 `$PATH` 上的每个 CLI，并打印一张按智能体维度的可用性表格。 |
| `tools` | 以 JSON 列出 Remote 能力名称与描述。 |
| `call <name> [json-args]` | 通过 `/v1` 调用运行中实例上的 Remote 能力。 |
| `agent "<goal>"` | `nomi_agent_run` 能力的便捷包装。 |
## 共享环境变量
下列变量由后端读取，不论被哪个宿主嵌入。
| 环境变量 | 读取方 | 作用 |
|---|---|---|
| `NOMIFUN_DATA_DIR` | 所有宿主 | 当宿主选择遵循该值时，作为后端数据目录的真值来源。桌面外壳会附加 `/Nomi`：设置该环境变量时目录为 `$NOMIFUN_DATA_DIR/Nomi`；未设置时目录为按用户的应用数据默认值（见[下文](#数据目录与工作目录的语义)）。独立 Web 宿主与 `nomicore` 二进制则按字面值将其作为 `--data-dir` 的默认值（不附加任何后缀）。 |
| `NOMIFUN_WORK_DIR` | `nomicore` | `--work-dir`（按会话区分的工作区根）的回退值。 |
| `JWT_SECRET` | `nomifun-app` | 用于签发会话 JWT 的密钥。解析顺序见 [鉴权密钥解析](#鉴权密钥解析)。 |
| `NOMIFUN_HTTPS` | `nomifun-auth::CookieConfig` | 取真值时，会话与 CSRF cookie 会带上 `Secure` 标记和 `SameSite=Strict`。当应用通过 HTTPS 暴露（TLS 反向代理等）时请打开。默认 `false` → 不带 `Secure` 标记，`SameSite=Lax`。 |
| `SHELL` | 智能体引擎（Linux/macOS） | 智能体引擎派生子进程时使用的 shell。在 systemd 下的 Linux 服务器上请显式设置（系统账户通常没有 `$SHELL`）。 |
| `NOMIFUN_URL` | `nomicore call`, `nomicore agent` | 调用 Remote capability 时使用的运行中实例 base URL。 |
| `NOMIFUN_COMPANION_TOKEN` | `nomicore call`, `nomicore agent` | 访问 `/v1` Remote capability 路由的 companion access token。 |
代码库不集成 `SENTRY_DSN`：这个环境变量并未被读取。
## 后端常量
来源：[`crates/backend/nomifun-common/src/constants.rs`](../../crates/backend/nomifun-common/src/constants.rs)。
这些是编译期值，不是环境变量——列在这里只是为了让运维方了解相关上限。
| 常量 | 取值 | 用途 |
|---|---|---|
| `DEFAULT_HOST` | `127.0.0.1` | `nomicore` 的默认 `--host`。 |
| `DEFAULT_PORT` | `25808` | `nomicore` 的默认 `--port`。（Web 宿主将其覆写为 `8787`。） |
| `BODY_LIMIT` | `10 MiB` | 应用于每条路由的默认请求体大小限制。需要更大的路由（例如 `/api/fs/upload`）会安装自己的更大限制。 |
| `UPLOAD_MAX_SIZE` | `30 MiB` | 文件上传路由（`/api/fs/upload`）的上限。 |
| `REMOTE_IMAGE_MAX_SIZE` | `5 MiB` | 下载聊天中引用的远程图片时的上限。 |
| `COOKIE_NAME` | `nomifun-session` | 会话 cookie。 |
| `CSRF_COOKIE_NAME` | `nomifun-csrf-token` | CSRF cookie（不是 HttpOnly——JavaScript 需要读取它）。 |
| `CSRF_HEADER_NAME` | `x-csrf-token` | 与 CSRF cookie 值对应的请求头（Double Submit Cookie 模式）。 |
| `COOKIE_MAX_AGE_DAYS` | `30` | Cookie 的 `Max-Age`。 |
| `SESSION_EXPIRY` | `24h` | JWT 在需要刷新前的有效期。 |
| `HEARTBEAT_INTERVAL_MS` / `HEARTBEAT_TIMEOUT_MS` | `30000` / `60000` | WebSocket 的心跳 ping/pong。 |
## 数据目录与工作目录的语义
- `data-dir` 存放 SQLite 数据库（`nomifun-backend.db*`）、各智能体状态、
Bun 缓存、日志文件，以及任何嵌入式扩展数据。把它当成普通数据库来
对待——做好备份、限制权限。两个同时运行的后端共享它的情况已被机制
性地阻止（见下面的服务器锁）。
- 三个宿主（`nomifun-desktop`、`nomifun-web`、独立的 `nomicore`
二进制）通过 `nomifun_app::cli::default_data_dir()` 解析出**同一个
默认**数据目录：Windows 上是 `%LOCALAPPDATA%\NomiFun\Nomi`，macOS
上是 `~/Library/Application Support/NomiFun/Nomi`，Linux 上是
`$XDG_DATA_HOME/NomiFun/Nomi`（通常为 `~/.local/share/NomiFun/Nomi`），
经 `dirs` crate 解析；当 OS 报告不出用户目录时的极端回退是
`<system temp>/nomifun-data/Nomi`。所有宿主共用一个默认值是有意为
之：开发循环（`bun run serve:web`、`dev:web`、`dev`）与已安装
的桌面应用读写同一份状态——配置一次提供商或伙伴，处处可测；排查
问题也只需要看一个目录。想要隔离的沙箱时，把 `NOMIFUN_DATA_DIR`
或 `--data-dir` 指到别处即可。
- 后端启动时（早于打开数据库）会对 `{data_dir}/server.lock` 取一把
OS 级**排他锁**。同一数据目录上的第二个后端进程会快速失败，错误
信息会指出持有者（pid + 可执行文件名）并给出两条出路：关掉另一个
实例，或用 `NOMIFUN_DATA_DIR` / `--data-dir` 给这一个指一个独立
目录。锁是 advisory 的（经 `fs2` 走 `flock` / `LockFileEx`），进程
退出或崩溃时由 OS 自动释放——残留的 `server.lock` 文件无害。
`nomicore doctor` 与 `mcp-*` stdio 子命令不取这把锁（doctor 设计上
就允许与运行中的服务器并存）。
- `work-dir` 存放按会话区分的工作区。未设置时按以下顺序解析：
`--work-dir` → 非空的 `NOMIFUN_WORK_DIR` 环境变量 → 数据目录本身。
会话会在 `<work-dir>/conversations/` 下创建子目录；删除会话同时
删除其工作区。
- 桌面外壳使用上述共享默认值。设置 `NOMIFUN_DATA_DIR` 后会附加
`/Nomi`：目录变为 `$NOMIFUN_DATA_DIR/Nomi`——覆盖语义不变。旧版
构建默认在 `<system temp>/nomifun-data/Nomi`；首次以新默认启动时，
既有的 temp 根安装会被自动搬迁（一次性；旧目录保留为备份，数据库
中存储的绝对路径会被改写）。
- Web 宿主按字面值使用该值——`--data-dir`（或 `NOMIFUN_DATA_DIR`）
原样生效，不附加 `/Nomi` 后缀——因此 Docker（`/data`）与 systemd
（`/var/lib/nomifun`）部署不受影响。两者都未设置时，回退到同一个
共享的按用户默认目录；旧的相对 `data` 默认值已不复存在。
## 鉴权密钥解析
`JwtService` 由单一密钥构造；`AppServices::from_config` 按以下顺序解析它：
1. 若已设置，使用 `JWT_SECRET` 环境变量。
2. 否则，使用系统用户行（`system_default_user.jwt_secret`）中持久化的值。
3. 否则，生成一个全新的强随机密钥，并**持久化到数据库**供后续启动使用。
修改密码流会顺带轮换 JWT 密钥，使所有现有会话失效。
同一密钥还会用于派生加密钥（`derive_encryption_key`），用于对存储在
数据库中的机密（提供商密钥、MCP OAuth token 等）做静态加密。
## TLS / HTTPS Cookie 处理
NomiFun 自身不做 TLS 终止——请在前面放一个负责 TLS 终止的反向代理
（Caddy、nginx 等）。届时：
- 设置 `NOMIFUN_HTTPS=true`，使 cookie 带上 `Secure` 标记和
`SameSite=Strict`。否则浏览器会在 HTTPS 响应上拒收 `Secure` cookie，
登录看似会无声失败。
- `/ws` 上的 WebSocket 升级无需额外的请求头即可穿过任何符合标准的
代理；Caddy 开箱即用。
可参考 [`guides/web-server-deployment.md`](../guides/web-server-deployment.md)
中完整的 Caddy + Docker 示例。
## 日志
- 所有日志同时写入 stdout（让 `journalctl`/`docker logs` 能捕捉到）以及
`<log-dir>/nomicore.log` 上的按日滚动文件。
- `--log-level` 接受完整的 [`tracing` `EnvFilter`](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html)
指令：一个全局级别，或一组以逗号分隔的按 target 覆盖项。
示例：
- `info` —— 全局 info。
- `debug` —— 全局 debug。较啰嗦；适合短时复现。
- `info,nomifun_mcp=trace` —— 默认 info，MCP 模块为 trace。
- `warn,nomifun_conversation=info,nomifun_terminal=debug` —— 整体
更安静；会话引擎为 normal/info；终端为 debug。
不存在另一套 `RUST_LOG` 通路——`--log-level`（或宿主中等价的环境驱动
开关）是唯一的总开关。
## 另见
- [Web 服务部署](../guides/web-server-deployment.md) —— 用 Docker、
systemd、Caddy 运行 `nomifun-web`。
- [作为桌面应用运行 Nomi](../guides/desktop-app.md) —— 桌面端专属配置。
- [API 概览](./api-overview.zh.md) —— 配置完成并启动后，后端对外暴露
了什么。
- [疑难排查](./troubleshooting.zh.md) —— 配置在运行时出错时的症状与
修复方法。
Reference in New Issue View Git Blame Copy Permalink