文档
运行时配置
选择实际控制每个运行时的进程、数据目录、凭证类型和集成设置。
从英文自动翻译。 查看英文原文
配置所有者
sidecar通过以下方式读取环境配置 AppConfigService 中 apps/sidecar/src/config.ts。层在构造时读取这些值，并将 AppConfig 值传递给需要它的服务。更改父 shell 变量不会改变已经运行的服务。
Tauri 在启动子进程时提供自己的启动令牌和应用程序数据/迁移路径。浏览器预览使用Vite端连接变量。移动设备存储配对的桌面连接和设备凭据。文档站点具有单独的 Worker 绑定和独立的本地 Studio 进程。它们不共享通用配置文件。
配置您想要更改的行为的所有者。例如，设置 CLI 迁移 URL 不会重定向本机桌面数据库，配置文档助手不会提供桌面 AI 提供商凭据。
启动一个孤立的 sidecar
CADCAMFUN_TOKEN=local-development-token \
CADCAMFUN_DATA_DIR=/tmp/cadcamfun-config-example \
CADCAMFUN_MIGRATIONS_DIR="$PWD/packages/db/drizzle" \
CADCAMFUN_AI_HOST=direct \
CADCAMFUN_AI_OFFLINE=1 \
bun --no-env-file apps/sidecar/src/main.ts这使用一次性目录和示例开发令牌。为您自己的流程选择合适的令牌。服务器在指定端口上绑定环回；从其就绪事件中读取该端口。保持 stdin 打开，因为关闭它就意味着关闭。该命令故意显式传递设置并禁用 Bun 的自动环境文件加载。
对于正常的本机循环，使用 bun run desktop:dev。它在启动 Tauri 之前准备 sidecar 二进制文件和迁移，Tauri 拥有生成的进程连接。不要启动第二个手动 sidecar 并假设本机 webview 将附加到它。
所需的连接和存储设置
| 环境 | 默认 | 行为 |
|---|---|---|
CADCAMFUN_TOKEN | 必需的 | 为受保护的本地 API 路由编辑了应用程序承载凭证。 |
CADCAMFUN_DATA_DIR | 必需的 | sidecar 管理的本地状态的根。数据库是 cadcamfun.db 在它下面。 |
CADCAMFUN_MIGRATIONS_DIR | 缺席的 | 传递到数据库层的迁移目录。如果没有它，打开数据库不会创建或升级应用程序表。 |
CADCAMFUN_APP_URL | 配置中不存在 | 提供给帐户链接集成的基本 URL。相关服务决定其后备。 |
CADCAMFUN_DEBUG_LINKS | 错误的 | 在支持它们的处理程序中启用帐户链接的开发响应字段。 |
数据目录是存储根，而不是HTTP绑定地址。主服务器的监听器固定为 127.0.0.1 具有临时端口。同伴网络使用自己显式启用的 HTTPS 网关；更改 URL 设置不会使环回侦听器公开。
保持配置的迁移目录与二进制文件一致。当无法计划、备份或应用迁移时，启动可能会在准备就绪之前失败。数据库参考解释了事务和备份行为；省略迁移后缺少表是配置问题，而不是证明项目已删除。
应用程序令牌被读取为经过编辑的值，并且永远不会出现在配置日志中。此页面上的每个设置都会被读取一次， apps/sidecar/src/config.ts;更改的值只有在 sidecar 重新启动后才会生效。
AI主机和连接
| 环境 | 默认 | 行为 |
|---|---|---|
CADCAMFUN_AI_HOST | nikcli | 选择 nikcli 或 direct。直接主机不添加嵌入式持久工具循环和专家调度程序。 |
CADCAMFUN_AI_OFFLINE | 错误的 | 禁用网络提供商目录加载和实时网络搜索处理程序。它不是本地模型实现。 |
CADCAMFUN_AI_MINIMAX_BASE_URL | 缺席的 | 嵌入式 MiniMax 配置的可选修剪端点覆盖。 |
提供商密钥由凭证 API 管理，并由 AI 服务保存在 <dataDir>/ai/credentials.json。它们不是通过为每个提供者发明一个未记录的环境变量来提供的。使用提供者/模型状态端点来确定配置的内容和 人工智能引导 用于支持的直接模型路由。
离线模式不会将云提供商呼叫转变为离线应答。配置的直接或嵌入式模型仍然需要其提供者连接才能进行推理。本地优先的产品保留本地项目，没有模型连接；该存储属性与离线人工智能推理不同。
运营商策略加载自 <dataDir>/ai/policy.json。嵌入式主机将其自己的工作/配置目录隔离在应用程序的 AI 存储下方。策略、凭证、会话上下文和提供者目录缓存具有不同的用途；复制一个文件不会重建对话的整个运行时间。
帐户和计费集成
| 环境 | 使用 | 缺席时 |
|---|---|---|
STRIPE_SECRET_KEY | 出站 Stripe API 身份验证。 | 付费结帐和计费门户集成不可用。 |
STRIPE_WEBHOOK_SECRET | 验证已签名的 Stripe Webhook 有效负载。 | Webhook 处理程序在没有验证配置的情况下拒绝摄取。 |
STRIPE_PRICE_BASIC, STRIPE_PRICE_PRO, STRIPE_PRICE_ENTERPRISE | 付费计划的价格 ID。空白值将被忽略。 | 缺少的映射无法识别该计划的已配置结帐价格。 |
CRON_SECRET | 用于 cron 维护的附加共享凭据。 | 该守卫不需要额外的 cron 秘密；申请持票人入场仍然适用。 |
ADMIN_EMAIL | 帐户/服务策略使用的管理员身份。 | 本地安装的配置文件保留其服务实施的本地管理行为。 |
这些设置配置集成；他们无法确定远程帐户、价格、订阅或 Webhook 交付是否存在。检查操作的实际失败情况和运行服务状态。不要推断表的存在意味着相关的托管功能已完全配置。
AppConfig 接口还包含测试注入挂钩，例如替换模型工厂和 Stripe API 库。它们不是该生产配置层读取的环境变量。将测试挂钩保留在部署指令之外，除非正在运行的主机明确公开它们。
计费试用路线开始 14 天 PRO 审判 （TRIAL_DAYS 中 apps/sidecar/src/repos/billing-repo.ts，使用者 http/billing.ts）。可用的计划是 FREE, BASIC, PRO， 和 ENTERPRISE;只有三个付费计划需要 STRIPE_PRICE_* 环境。
日志和遥测
OTEL_EXPORTER_OTLP_ENDPOINT 启用 sidecar 的 OTLP/HTTP 跟踪、指标和日志导出器。如果没有非空白端点，则禁用此可选遥测层。导出器代码构建特定于信号的端点；配置支持这些信号的收集器。
正常的 sidecar 日志记录与遥测导出是分开的。 Stdout 承载 shell 使用的 JSON 就绪/错误协议，而日志则定向到 stderr。诊断启动时，保留第一个相关错误及其操作上下文，而不是期望应用程序窗口包含每个初始化详细信息。
不要在诊断包中包含启动令牌、提供程序密钥、会话令牌或完整凭据文件。源路径、方法/状态、端点 ID、非秘密项目 ID 和失败的数据库操作通常提供更安全、更有用的起点。
客户端配置
仅浏览器桌面预览在以下情况下使用伪造的内存中 API： VITE_SIDECAR_URL 缺席。要将其连接到手动启动的 sidecar，请设置该 URL 并 VITE_SIDECAR_TOKEN 在启动 Vite 之前。打包的 Tauri 路径改为从 shell 获取连接。
VITE_SIDECAR_URL=http://127.0.0.1:READY_PORT \
VITE_SIDECAR_TOKEN=local-development-token \
bun run --filter @cadcamfun/desktop dev替换端口占位符。 vite设置属于前端开发流程；更改它们不会重新启动或重新配置 sidecar。浏览器访问受 sidecar 的环回/Tauri CORS 策略和正常承载许可的约束。
移动配对通过移动应用程序存储其桌面地址、证书指纹和设备令牌。更改桌面的启动令牌不是配对手机的正常方法。使用 配对程序 并在需要时撤销各个设备。
数据库路径选择
| 过程 | 评选规则 |
|---|---|
| 原生桌面边车 | Tauri 提供的应用程序数据目录，然后 cadcamfun.db. |
| 手动边车 | CADCAMFUN_DATA_DIR/cadcamfun.db. |
| 数据库迁移 CLI | DATABASE_URL，删除初始的 file:;否则与流程相关 ./data/cadcamfun.db. |
根 db:migrate 包装纸 | 运行数据库包脚本，因此默认解析范围内 packages/db. |
| 文档工作室 | CADCAMFUN_DB， 然后 DATABASE_URL，然后是存储库根目录 data/cadcamfun.db。该文件必须存在。 |
因此，空的项目列表可能意味着您打开了另一个有效的数据库。在更改迁移或复制数据之前记录进程和绝对选择的路径。帐户会话还可以更改哪些资源可见，而无需更改文件。
应用并验证更改
- 识别所有者进程和当前存储路径。在更改存储或迁移之前保留所需的数据。
- 彻底停止该进程并更新其显式启动配置或本机设置。
- 再次启动并等待其实际的就绪结果。解析新连接而不是重用旧端口。
- 检查公共卫生呼叫和已承认的受保护呼叫。
- 验证特定行为：预期项目出现、提供程序状态更改、网关变得可访问或配置的遥测收集器收到预期信号。
配置值的存在与工作外部集成不同。更改后读取服务结果。具有默认值的配置值应与接收服务决定其回退的可选值区分开来。
配置诊断
如果在准备就绪之前初始化失败，请检查所需的设置、迁移可用性、目录访问和第一层构建错误。如果运行状况成功但受保护的调用失败，请检查令牌类型和当前进程。如果项目运行时提供商失败，请检查 AI 配置而不是重置数据库。
如果 Studio 在托管网站上不可用，则其生产 API 会有意返回 503；针对选定的现有文件启动其本地 Bun 进程。如果文档助手不可用，请检查 Worker 绑定或其配置的 nikcli 后端。这两种诊断都不需要更换桌面凭据。
证据来源： apps/sidecar/src/config.ts, layers.ts, main.ts, observability.ts, services/ai.ts, packages/db/src/migrate.ts， 和 packages/web/script/studio-server.ts.
一张表中的所有边车设置
AppConfigService 是 sidecar 中唯一读取环境的地方。该表按读取顺序列出了它读取的每个变量。如果注明，空或空格的可选值将被视为不存在。
| 多变的 | 类型 | 默认 | 使用者 |
|---|---|---|---|
CADCAMFUN_TOKEN | 编辑字符串 | 必需的 | 每个受保护路由的承载中间件 |
CADCAMFUN_DATA_DIR | 细绳 | 必需的 | 数据库、AI存储、插件、伴侣、上传 |
CADCAMFUN_MIGRATIONS_DIR | 细绳 | 缺席的 | 数据库层；缺席意味着没有创建模式 |
CADCAMFUN_APP_URL | 细绳 | 缺席的 | 帐户电子邮件中的链接（旧版 NEXTAUTH_URL) |
CADCAMFUN_DEBUG_LINKS | 布尔值 | false | 响应中的回声重置和魔法链接（仅限开发） |
CADCAMFUN_AI_OFFLINE | 布尔值 | false | 没有提供商目录下载，也没有实时网络搜索 |
CADCAMFUN_AI_HOST | nikcli | direct | nikcli | 助理主持人；任何其他值都会导致启动失败 |
CADCAMFUN_AI_MINIMAX_BASE_URL | 绳子，修剪过的 | 缺席的 | 嵌入式主机的 MiniMax 端点 |
STRIPE_WEBHOOK_SECRET | 细绳 | 缺席的 | 没有它，Stripe webhook 将被拒绝 |
STRIPE_SECRET_KEY | 编辑字符串 | 缺席的 | 如果没有它，付费结帐和计费门户将不可用 |
STRIPE_PRICE_BASIC, _PRO, _ENTERPRISE | 绳子，修剪过的 | 缺席的 | 每个付费计划的价格 ID；空白值被忽略 |
CRON_SECRET | 细绳 | 缺席的 | 共享秘密 /api/cron/*;如果没有它，路线将向本地应用程序开放 |
ADMIN_EMAIL | 细绳 | 缺席的 | 管理员电子邮件；默认情况下，本地配置文件管理其自己的安装 |
OTEL_EXPORTER_OTLP_ENDPOINT | 绳子，修剪过的 | 缺席的 | OTLP/HTTP 收集器基本 URL；如果没有它，遥测就会关闭 |
所报告的申请 version 已在代码中固定（6.0.0），不是从环境中读取。
无效值停止启动
缺少必需的变量，或者无法解析的值（例如 CADCAMFUN_AI_HOST=local），配置层失败。然后，sidecar 会打印错误而不是就绪行，并且桌面会报告启动失败。
在 sidecar 配置外部读取变量
| 多变的 | 读者 | 目的 |
|---|---|---|
DATABASE_URL | packages/db 迁移脚本和 drizzle-kit | 目标为 db:migrate / db:generate;领先的 file: 被剥夺了。默认 ./data/cadcamfun.db 相对于 packages/db. |
CADCAMFUN_DB， 然后 DATABASE_URL | Web Studio 服务器（packages/web/script/studio-server.ts) | 本地Studio打开的数据库；默认 data/cadcamfun.db 在存储库根目录下。 |
NIKCLI_LOCALE, NIKCLI_LANGUAGE, NIKCLI_REGION | 嵌入式辅助主机 | 覆盖助理的语言和区域。 |
LC_ALL, LC_MESSAGES, LANG, LANGUAGE, TZ | 嵌入式辅助主机 | 未设置覆盖时的系统区域设置和时区检测。 |
桌面 shell 将三个变量传递给它启动的 sidecar： CADCAMFUN_TOKEN （每次启动一个新的随机令牌）， CADCAMFUN_DATA_DIR （应用程序数据目录）和 CADCAMFUN_MIGRATIONS_DIR （捆绑迁移）。桌面应用程序本身启动的环境中必须存在其他任何内容。
数据目录中包含哪些内容
cadcamfun.db SQLite database (+ -wal / -shm while running)
backups/ pre-migration snapshots, newest five kept
auth-secret signing secret for account session tokens (0600)
auth-revoked.json revoked session tokens
ai/
credentials.json provider API keys (owner-readable only)
policy.json operator policy for the assistant
skills/ user skills
session-owners/ which account owns which assistant session
nikcli/ isolated working and config dirs of the embedded host
plugins/ assistant plugins loaded at startup
plugins-registry/ installed marketplace plugin files
companion/ gateway TLS cert.pem and key.pem (0600)
storage/ file storage for library import/export, entity I/O and plugins
uploads/profiles/ profile pictures
downloads/ files served by /api/download
waitlist.json local waitlist entries目录是在首次使用时创建的，因此全新安装仅包含其功能所涉及的目录。在应用程序停止的情况下备份整个目录：数据库、凭据、身份验证密钥和伴随密钥属于同一组。配对的配套设备存储在数据库的键值表中，而不是存储在 companion/.
将目录视为机密
ai/credentials.json, auth-secret 伴随的私钥是凭证。不要提交开发数据目录或将其附加到错误报告中。
配置示例
export CADCAMFUN_TOKEN=dev-$(openssl rand -hex 16)
export CADCAMFUN_DATA_DIR="$(mktemp -d)"
export CADCAMFUN_MIGRATIONS_DIR="$PWD/packages/db/drizzle"
export CADCAMFUN_AI_HOST=direct
export CADCAMFUN_AI_OFFLINE=true
bun --no-env-file apps/sidecar/src/main.tsexport CADCAMFUN_APP_URL=http://localhost:4321
export CADCAMFUN_DEBUG_LINKS=true # reset/magic links appear in responsesexport OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318export STRIPE_SECRET_KEY=sk_test_...
export STRIPE_WEBHOOK_SECRET=whsec_...
export STRIPE_PRICE_PRO=price_...从未设置 CADCAMFUN_DEBUG_LINKS 外部开发：它将帐户链接放入 HTTP 响应中。