ODS .env 生成机制所有配置写入点全图解析6大写入点完整指南【免费下载链接】ODSTurn your PC, Mac, or Linux box into an AI server. LLM inference, chat UI, voice, agents, workflows, RAG, and image generation.项目地址: https://gitcode.com/GitHub_Trending/dr/ODS在 ODS把你的 PC、Mac 或 Linux 主机变成 AI 服务器的一键安装项目中.env是整个系统唯一的配置中枢LLM 模型、GPU 分配、端口、密钥、网络绑定全部集中在安装目录下的$INSTALL_DIR/.env这一个文件里。Docker Compose 读它ods-cli读写它备份与预设也围绕它展开。很多用户重装后担心我改过的端口和 API key 会不会被覆盖——答案是 ODS 有一套精心设计的合并策略重新生成.env时你的自定义值会被安全保留。本文用一张写入点全图讲清楚.env从出生到验证的完整生命周期。️ .env 写入点全图一图看懂 6 大写入时机ODS 的安装器采用分阶段Phase架构位于 ods/installers/phases/。对.env有写操作的共 6 处按时间顺序如下#阶段/模块文件写入内容1Phase 06 目录生成06-directories.sh主生成整个.env的诞生2Phase 08 镜像拉取08-images.sh回填校验后的LLAMA_SERVER_IMAGE、HERMES_AGENT_IMAGE3Phase 09 离线模式09-offline.sh清空云端 API key追加离线配置块4Phase 11 服务启动11-services.sh启动前对个别键做原子修补5CLI 日常操作ods-cli_env_set/_env_unset增改删任意键6预设与备份ods-backup.sh / ods-restore.sh整体快照.env及恢复记住一句话Phase 06 是出生其余 5 处都是后续编辑且编辑都遵循只动目标键、不碰其他行的原则。 Phase 06.env 的出生时刻核心章节.env的主生成逻辑集中在 06-directories.sh 的generate-env步骤第 309 行起。它做了三件事1️⃣ 合并策略重装不丢配置安装器检测到已有.env时会记录日志 Found existing .env — preserving user-configured values06-directories.sh#L315-L318。随后通过三个内部读取函数取值_env_get读旧值没有则用默认值——API key、自定义端口、手动密钥都靠它保命_env_get_preserve_empty空值也算用户显式清空重新运行时保留这种明确状态_env_get_explicit_first命令行参数如--lan优先于旧.env旧值兜底。也就是说--lan参数 旧.env中的值 内置默认值优先级清晰可预期网络绑定逻辑见 06-directories.sh#L678-L679 的注释。2️⃣ 密钥生成一次性随机永不重生所有敏感值都用openssl rand现场生成06-directories.sh#L430-L521包括WEBUI_SECRET、N8N_PASS、OPENCODE_SERVER_PASSWORD各服务登录口令LITELLM_KEY、LITELLM_LEMONADE_API_KEY模型路由代理 keyDASHBOARD_API_KEY、ODS_AGENT_KEY、SHIELD_API_KEYODS_SESSION_SECRETmagic-link 签名、HERMES_DASHBOARD_SESSION_TOKEN容器重启后可重连QDRANT_API_KEY、DIFY_SECRET_KEY、Langfuse 全家桶等关键点重装时这些密钥直接沿用旧值_env_get读到就复用不会出现重启一次所有会话失效的灾难。3️⃣ 安全落盘 Schema 校验生成时在子 shell 中临时收紧umask 077文件从创建那一刻起就是 0600 权限杜绝密钥文件短暂可读的窗口期06-directories.sh#L796-L805落盘后再chmod 600双保险紧接着用 scripts/validate-env.sh 对照 .env.schema.json 做快速失败校验——缺键或未知键会直接报错并指向日志而不是让你装完才发现配置缺失。生成的.env内容按区块组织带日期戳注释头Generated by installer v… on …ODS 版本、网络绑定、LLM 后端模式、云端 API key、模型设置、llama.cpp 运行时调优、各服务 CPU 预算等。GPU 分配方案则以Base64 编码的 JSONGPU_ASSIGNMENT_JSON_B64存入保证单行语法安全。 写入点 2–4安装后半程的微调Phase 0808-images.sh#L127-L131镜像实际拉取并校验通过后才把LLAMA_SERVER_IMAGE写回.env已存在则 sed 替换不存在则追加。这确保记录的是真实跑通的镜像版本呼应项目的镜像标签钉住策略 docs/ADR-IMAGE-TAG-PINNING.mdPhase 0909-offline.sh#L29-L34离线安装时主动清空ANTHROPIC_API_KEY/OPENAI_API_KEY/BRAVE_API_KEY并追加离线配置块防止以为离线了其实还在偷渡云端Phase 1111-services.sh#L251-L271服务启动前用 awk 临时文件做原子单键更新_phase11_env_set保证并发或中断时不写坏文件。⌨️ 写入点 5ods-cli 的日常读写接口装完之后你所有的ods命令操作最终都落到 ods-cli 中的三个底层函数ods-cli#L98-L126_env_set key value存在则原位替换awk 实现避免 sed 分隔符撞值不存在则追加_env_unset key整行删除该键_env_get_raw key只读取值自动剥离 CRLF。典型应用场景ods update完成后把新版本号持久化到ODS_VERSIONods gpu reassign重新计算分配后写回GPU_COUNT和GPU_ASSIGNMENT_JSON_B64且失败时自动回滚到之前的.env备份预设系统ods preset save/load则直接把整个.env复制为快照、再整体还原实现一键回滚到某个模型模式组合ods-cli#L3097-L3159。️ 读取与展示安全解析密钥脱敏写入讲完了读取同样有讲究安全读取所有脚本统一使用 lib/safe-env.sh 的load_env_file解析.env——纯文本解析、绝不 eval杜绝命令注入还专门处理了 Windows 编辑器的 CRLF、base64 值中的、以及 Bash 只读变量UID等边界情况安全序列化反向写入时用 lib/dotenv-quote.sh 的dotenv_quote保证同一行在 Bash、Docker Compose 和 ODS 读取器三处语义一致脱敏展示ods config命令展示.env时依据.env.schema.json对密钥类键打码显示明文永远以cat .env为准ods-cli#L2168-L2249。 速查清单常见场景该改哪里场景操作局域网访问--lan重装或手改BIND_ADDRESS0.0.0.0换模型/上下文改LLM_MODEL、GGUF_FILE、MAX_CONTEXT或跑ods模型命令接入外部 LLM填EXTERNAL_LLM_URL/EXTERNAL_LLM_PROVIDER/EXTERNAL_LLM_MODEL调 GPU 分配ods gpu reassign自动备份回滚保护换镜像版本改LLAMA_SERVER_IMAGE下次 Phase 08 会校验回滚配置ods preset load或 ods-restore.sh✅ 总结ODS 的.env机制可以浓缩为三句话单一事实来源——所有运行时配置只写在$INSTALL_DIR/.envDocker Compose 与各脚本共用同一份生成即安全——umask 077 原子落盘 600 权限 schema 快速失败校验合并式覆盖——Phase 06 重新生成时保留你的密钥与自定义值后续 5 个写入点全部只改目标键。理解了这张写入点全图你就能在遇到问题时快速定位是安装时生成错了查 Phase 06 日志还是 CLI 操作改乱了查ods-cli还是镜像版本漂移查 Phase 08。更多排障思路可参考 docs/TROUBLESHOOTING.md 与 docs/INSTALLER-ARCHITECTURE.md。【免费下载链接】ODSTurn your PC, Mac, or Linux box into an AI server. LLM inference, chat UI, voice, agents, workflows, RAG, and image generation.项目地址: https://gitcode.com/GitHub_Trending/dr/ODS创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ODS .env 生成机制：所有配置写入点全图解析（6大写入点完整指南）
ODS .env 生成机制所有配置写入点全图解析6大写入点完整指南【免费下载链接】ODSTurn your PC, Mac, or Linux box into an AI server. LLM inference, chat UI, voice, agents, workflows, RAG, and image generation.项目地址: https://gitcode.com/GitHub_Trending/dr/ODS在 ODS把你的 PC、Mac 或 Linux 主机变成 AI 服务器的一键安装项目中.env是整个系统唯一的配置中枢LLM 模型、GPU 分配、端口、密钥、网络绑定全部集中在安装目录下的$INSTALL_DIR/.env这一个文件里。Docker Compose 读它ods-cli读写它备份与预设也围绕它展开。很多用户重装后担心我改过的端口和 API key 会不会被覆盖——答案是 ODS 有一套精心设计的合并策略重新生成.env时你的自定义值会被安全保留。本文用一张写入点全图讲清楚.env从出生到验证的完整生命周期。️ .env 写入点全图一图看懂 6 大写入时机ODS 的安装器采用分阶段Phase架构位于 ods/installers/phases/。对.env有写操作的共 6 处按时间顺序如下#阶段/模块文件写入内容1Phase 06 目录生成06-directories.sh主生成整个.env的诞生2Phase 08 镜像拉取08-images.sh回填校验后的LLAMA_SERVER_IMAGE、HERMES_AGENT_IMAGE3Phase 09 离线模式09-offline.sh清空云端 API key追加离线配置块4Phase 11 服务启动11-services.sh启动前对个别键做原子修补5CLI 日常操作ods-cli_env_set/_env_unset增改删任意键6预设与备份ods-backup.sh / ods-restore.sh整体快照.env及恢复记住一句话Phase 06 是出生其余 5 处都是后续编辑且编辑都遵循只动目标键、不碰其他行的原则。 Phase 06.env 的出生时刻核心章节.env的主生成逻辑集中在 06-directories.sh 的generate-env步骤第 309 行起。它做了三件事1️⃣ 合并策略重装不丢配置安装器检测到已有.env时会记录日志 Found existing .env — preserving user-configured values06-directories.sh#L315-L318。随后通过三个内部读取函数取值_env_get读旧值没有则用默认值——API key、自定义端口、手动密钥都靠它保命_env_get_preserve_empty空值也算用户显式清空重新运行时保留这种明确状态_env_get_explicit_first命令行参数如--lan优先于旧.env旧值兜底。也就是说--lan参数 旧.env中的值 内置默认值优先级清晰可预期网络绑定逻辑见 06-directories.sh#L678-L679 的注释。2️⃣ 密钥生成一次性随机永不重生所有敏感值都用openssl rand现场生成06-directories.sh#L430-L521包括WEBUI_SECRET、N8N_PASS、OPENCODE_SERVER_PASSWORD各服务登录口令LITELLM_KEY、LITELLM_LEMONADE_API_KEY模型路由代理 keyDASHBOARD_API_KEY、ODS_AGENT_KEY、SHIELD_API_KEYODS_SESSION_SECRETmagic-link 签名、HERMES_DASHBOARD_SESSION_TOKEN容器重启后可重连QDRANT_API_KEY、DIFY_SECRET_KEY、Langfuse 全家桶等关键点重装时这些密钥直接沿用旧值_env_get读到就复用不会出现重启一次所有会话失效的灾难。3️⃣ 安全落盘 Schema 校验生成时在子 shell 中临时收紧umask 077文件从创建那一刻起就是 0600 权限杜绝密钥文件短暂可读的窗口期06-directories.sh#L796-L805落盘后再chmod 600双保险紧接着用 scripts/validate-env.sh 对照 .env.schema.json 做快速失败校验——缺键或未知键会直接报错并指向日志而不是让你装完才发现配置缺失。生成的.env内容按区块组织带日期戳注释头Generated by installer v… on …ODS 版本、网络绑定、LLM 后端模式、云端 API key、模型设置、llama.cpp 运行时调优、各服务 CPU 预算等。GPU 分配方案则以Base64 编码的 JSONGPU_ASSIGNMENT_JSON_B64存入保证单行语法安全。 写入点 2–4安装后半程的微调Phase 0808-images.sh#L127-L131镜像实际拉取并校验通过后才把LLAMA_SERVER_IMAGE写回.env已存在则 sed 替换不存在则追加。这确保记录的是真实跑通的镜像版本呼应项目的镜像标签钉住策略 docs/ADR-IMAGE-TAG-PINNING.mdPhase 0909-offline.sh#L29-L34离线安装时主动清空ANTHROPIC_API_KEY/OPENAI_API_KEY/BRAVE_API_KEY并追加离线配置块防止以为离线了其实还在偷渡云端Phase 1111-services.sh#L251-L271服务启动前用 awk 临时文件做原子单键更新_phase11_env_set保证并发或中断时不写坏文件。⌨️ 写入点 5ods-cli 的日常读写接口装完之后你所有的ods命令操作最终都落到 ods-cli 中的三个底层函数ods-cli#L98-L126_env_set key value存在则原位替换awk 实现避免 sed 分隔符撞值不存在则追加_env_unset key整行删除该键_env_get_raw key只读取值自动剥离 CRLF。典型应用场景ods update完成后把新版本号持久化到ODS_VERSIONods gpu reassign重新计算分配后写回GPU_COUNT和GPU_ASSIGNMENT_JSON_B64且失败时自动回滚到之前的.env备份预设系统ods preset save/load则直接把整个.env复制为快照、再整体还原实现一键回滚到某个模型模式组合ods-cli#L3097-L3159。️ 读取与展示安全解析密钥脱敏写入讲完了读取同样有讲究安全读取所有脚本统一使用 lib/safe-env.sh 的load_env_file解析.env——纯文本解析、绝不 eval杜绝命令注入还专门处理了 Windows 编辑器的 CRLF、base64 值中的、以及 Bash 只读变量UID等边界情况安全序列化反向写入时用 lib/dotenv-quote.sh 的dotenv_quote保证同一行在 Bash、Docker Compose 和 ODS 读取器三处语义一致脱敏展示ods config命令展示.env时依据.env.schema.json对密钥类键打码显示明文永远以cat .env为准ods-cli#L2168-L2249。 速查清单常见场景该改哪里场景操作局域网访问--lan重装或手改BIND_ADDRESS0.0.0.0换模型/上下文改LLM_MODEL、GGUF_FILE、MAX_CONTEXT或跑ods模型命令接入外部 LLM填EXTERNAL_LLM_URL/EXTERNAL_LLM_PROVIDER/EXTERNAL_LLM_MODEL调 GPU 分配ods gpu reassign自动备份回滚保护换镜像版本改LLAMA_SERVER_IMAGE下次 Phase 08 会校验回滚配置ods preset load或 ods-restore.sh✅ 总结ODS 的.env机制可以浓缩为三句话单一事实来源——所有运行时配置只写在$INSTALL_DIR/.envDocker Compose 与各脚本共用同一份生成即安全——umask 077 原子落盘 600 权限 schema 快速失败校验合并式覆盖——Phase 06 重新生成时保留你的密钥与自定义值后续 5 个写入点全部只改目标键。理解了这张写入点全图你就能在遇到问题时快速定位是安装时生成错了查 Phase 06 日志还是 CLI 操作改乱了查ods-cli还是镜像版本漂移查 Phase 08。更多排障思路可参考 docs/TROUBLESHOOTING.md 与 docs/INSTALLER-ARCHITECTURE.md。【免费下载链接】ODSTurn your PC, Mac, or Linux box into an AI server. LLM inference, chat UI, voice, agents, workflows, RAG, and image generation.项目地址: https://gitcode.com/GitHub_Trending/dr/ODS创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考