Merge pull request #3680 from Frank-zhu2000/fix/3591-docker-upgrade-data

docs: document COW_DATA_DIR and cow-data volume for Docker upgrades

config.py

@@ -578,6 +578,10 @@ def load_config():
         # skip comment fields starting with an underscore
         if name.startswith("_"):
             continue
+        # A blank value is a placeholder (docker-compose lists every key as
+        # ''), not a request to wipe what the user saved in config.json.
+        if value == "":
+            continue
         if name in available_setting:
             logger.info("[INIT] override config by environ args: {}={}".format(
                 name, drag_sensitive({name: value})[name]))
@@ -696,7 +700,7 @@ def load_config():
     }
     injected = 0
     for conf_key, env_key in _CONFIG_TO_ENV.items():
-        if env_key not in os.environ:
+        if not os.environ.get(env_key):
             val = config.get(conf_key, "")
             if val:
                 os.environ[env_key] = str(val)

docker/docker-compose.yml

@@ -10,7 +10,9 @@ services:
     environment:
       COW_LANG: 'auto'
       CHANNEL_TYPE: 'web, weixin'
-      MODEL: 'deepseek-flash'
+      # Any value set here overrides the model chosen in the web console on
+      # every start. Unset, it defaults to deepseek-flash.
+      # MODEL: 'deepseek-flash'
       DEEPSEEK_API_KEY: ''
       DEEPSEEK_API_BASE: 'https://api.deepseek.com/v1'
       MINIMAX_API_KEY: ''

docs/guide/upgrade.mdx

@@ -84,7 +84,7 @@ sudo docker compose up -d
 ```
 
 <Tip>
-  Back up `config.json` before upgrading. For Docker deployments, mount the workspace directory as a volume to persist data across upgrades.
+  Back up `config.json` before upgrading. Settings and channel logins live in the mounted `./cow-data` directory and the workspace in `./cow`, so recreating the container keeps them. Environment variables given a value in `docker-compose.yml` override the same settings from the console on every start.
 </Tip>
 
 ## Desktop client upgrade

docs/ja/guide/upgrade.mdx

@@ -57,7 +57,7 @@ sudo docker compose up -d
 ```
 
 <Tip>
-  アップグレード前に `config.json` 設定ファイルのバックアップを推奨します。Docker 環境でデータを保持する場合は、volume マウントでワークスペースディレクトリを永続化できます。
+  アップグレード前に `config.json` 設定ファイルのバックアップを推奨します。設定とチャネルのログイン情報はマウントされた `./cow-data` ディレクトリに、ワークスペースは `./cow` に保存されるため、コンテナを再作成しても失われません。`docker-compose.yml` で値を設定した環境変数は、起動のたびにコンソールの同名設定を上書きします。
 </Tip>
 
 ## デスクトップクライアントのアップグレード

docs/zh/guide/upgrade.mdx

@@ -84,7 +84,7 @@ sudo docker compose up -d
 ```
 
 <Tip>
-  升级前建议备份 `config.json` 配置文件。Docker 环境下如需保留数据，可通过 volume 挂载持久化工作空间目录。
+  升级前建议备份 `config.json` 配置文件。配置和渠道登录信息保存在挂载的 `./cow-data` 目录，工作空间保存在 `./cow` 目录，重建容器不会丢失。`docker-compose.yml` 中填写了值的环境变量会在每次启动时覆盖控制台里的同名配置。
 </Tip>
 
 ## 客户端升级

tests/test_config_blank_env_override.py

@@ -0,0 +1,33 @@
+"""Blank environment placeholders must not wipe settings saved in config.json."""
+import json
+import os
+
+import config
+
+
+def _load(tmp_path, monkeypatch, saved, env):
+    (tmp_path / "config.json").write_text(json.dumps(saved))
+    monkeypatch.setenv("HOME", str(tmp_path))
+    monkeypatch.setenv("COW_DATA_DIR", str(tmp_path))
+    for key, value in env.items():
+        monkeypatch.setenv(key, value)
+    config.load_config()
+    return config.conf()
+
+
+def test_blank_env_keeps_saved_values(tmp_path, monkeypatch):
+    monkeypatch.delenv("FEISHU_APP_ID", raising=False)
+    conf = _load(tmp_path, monkeypatch,
+                 {"deepseek_api_key": "sk-saved", "feishu_app_id": "cli_saved"},
+                 {"DEEPSEEK_API_KEY": "", "FEISHU_APP_ID": ""})
+    assert conf.get("deepseek_api_key") == "sk-saved"
+    assert conf.get("feishu_app_id") == "cli_saved"
+    assert os.environ["FEISHU_APP_ID"] == "cli_saved"
+
+
+def test_non_blank_env_still_overrides(tmp_path, monkeypatch):
+    conf = _load(tmp_path, monkeypatch,
+                 {"deepseek_api_key": "sk-saved", "model": "saved-model"},
+                 {"DEEPSEEK_API_KEY": "sk-env", "MODEL": "env-model"})
+    assert conf.get("deepseek_api_key") == "sk-env"
+    assert conf.get("model") == "env-model"