feat: 完善知识库预览功能与配置管理优化

.env

@@ -0,0 +1,50 @@
+APP_NAME=X-Financial
+APP_ENV=local
+APP_DEBUG=true
+API_V1_PREFIX=/api/v1
+SETUP_COMPLETED=true
+VITE_SETUP_COMPLETED=true
+
+COMPANY_NAME=YGSOFT
+COMPANY_CODE=123
+ADMIN_EMAIL='admin@admin.com'
+VITE_COMPANY_NAME=YGSOFT
+VITE_COMPANY_CODE=123
+VITE_ADMIN_EMAIL='admin@admin.com'
+# Admin login credentials are stored separately under server/.secrets/
+
+WEB_HOST=10.10.10.122
+WEB_PORT=5173
+VITE_WEB_HOST=10.10.10.122
+VITE_WEB_PORT=5173
+
+SERVER_HOST=0.0.0.0
+SERVER_PORT=8000
+VITE_SERVER_HOST=0.0.0.0
+VITE_SERVER_PORT=8000
+SERVER_STARTUP_TIMEOUT=300
+SERVER_BLOCKING_STARTUP_TIMEOUT=12
+VITE_API_BASE_URL=/api/v1
+VITE_AUTH_IDLE_TIMEOUT_MINUTES=30
+ONLYOFFICE_ENABLED=true
+ONLYOFFICE_PUBLIC_URL=http://onlyoffice:80
+ONLYOFFICE_BACKEND_URL=http://main:8000
+ONLYOFFICE_JWT_SECRET=change-me-onlyoffice
+
+POSTGRES_HOST=10.10.10.189
+POSTGRES_PORT=5432
+POSTGRES_DB=postgres
+POSTGRES_USER=root
+POSTGRES_PASSWORD=8811614287327Leo
+VITE_POSTGRES_HOST=10.10.10.189
+VITE_POSTGRES_PORT=5432
+VITE_POSTGRES_DB=postgres
+VITE_POSTGRES_USER=root
+
+DATABASE_URL='postgresql+psycopg://root:8811614287327Leo@10.10.10.189:5432/postgres'
+SQLALCHEMY_ECHO=false
+
+REDIS_URL=
+VITE_REDIS_URL=
+
+CORS_ORIGINS='["http://10.10.10.122:5173"]'

docker-compose.yml

@@ -6,14 +6,15 @@ services:
     depends_on:
       onlyoffice:
         condition: service_started
-    environment:
+    environment:
-      WEB_HOST: 0.0.0.0
+      WEB_HOST: 0.0.0.0
-      SERVER_HOST: 0.0.0.0
+      SERVER_HOST: 0.0.0.0
-      SERVER_VENV_DIR: /tmp/x-financial-server-venv
+      SERVER_VENV_DIR: /tmp/x-financial-server-venv
-      ONLYOFFICE_ENABLED: "${ONLYOFFICE_ENABLED:-true}"
+      X_FINANCIAL_PREFER_ENV_FILE: "true"
-      ONLYOFFICE_PUBLIC_URL: "${ONLYOFFICE_PUBLIC_URL:-http://127.0.0.1:${ONLYOFFICE_PORT:-8082}}"
+      ONLYOFFICE_ENABLED: "${ONLYOFFICE_ENABLED:-true}"
-      ONLYOFFICE_BACKEND_URL: "${ONLYOFFICE_BACKEND_URL:-http://main:${SERVER_PORT:-8000}}"
+      ONLYOFFICE_PUBLIC_URL: "${ONLYOFFICE_PUBLIC_URL:-http://127.0.0.1:${ONLYOFFICE_PORT:-8082}}"
-      ONLYOFFICE_JWT_SECRET: "${ONLYOFFICE_JWT_SECRET:-x-financial-onlyoffice-dev-secret}"
+      ONLYOFFICE_BACKEND_URL: "http://main:${SERVER_PORT:-8000}"
+      ONLYOFFICE_JWT_SECRET: "${ONLYOFFICE_JWT_SECRET:-x-financial-onlyoffice-dev-secret}"
     ports:
       - "${WEB_PORT:-5173}:${WEB_PORT:-5173}"
       - "${SERVER_PORT:-8000}:${SERVER_PORT:-8000}"
@@ -38,25 +39,33 @@ services:
         chmod +x /app/start.sh /app/web/web_start.sh /app/server/server_start.sh &&
         cd /app &&
         ./start.sh all
-    healthcheck:
+    healthcheck:
-      test: ["CMD-SHELL", "curl -fsS http://127.0.0.1:${WEB_PORT:-5173}/ >/dev/null || exit 1"]
+      test: ["CMD-SHELL", "curl -fsS http://127.0.0.1:${WEB_PORT:-5173}/ >/dev/null || exit 1"]
-      interval: 15s
+      interval: 15s
-      timeout: 5s
+      timeout: 5s
-      retries: 10
+      retries: 10
-      start_period: 180s
+      start_period: 180s
-
+    networks:
-  onlyoffice:
+      - financial-internal
-    image: onlyoffice/documentserver:latest
+
-    container_name: x-financial-onlyoffice
+  onlyoffice:
+    image: onlyoffice/documentserver:latest
+    container_name: x-financial-onlyoffice
     restart: unless-stopped
     environment:
       JWT_ENABLED: "true"
       JWT_SECRET: "${ONLYOFFICE_JWT_SECRET:-x-financial-onlyoffice-dev-secret}"
     ports:
       - "${ONLYOFFICE_PORT:-8082}:80"
-    healthcheck:
+    healthcheck:
-      test: ["CMD-SHELL", "curl -fsS http://127.0.0.1/healthcheck >/dev/null || exit 1"]
+      test: ["CMD-SHELL", "curl -fsS http://127.0.0.1/healthcheck >/dev/null || exit 1"]
-      interval: 15s
+      interval: 15s
-      timeout: 5s
+      timeout: 5s
-      retries: 10
+      retries: 10
-      start_period: 60s
+      start_period: 60s
+    networks:
+      - financial-internal
+
+networks:
+  financial-internal:
+    name: financial-internal

nul

@@ -0,0 +1 @@
+/usr/bin/bash: line 1: rg: command not found

server/server_start.sh

@@ -94,6 +94,13 @@ ENV_OVERRIDE_ONLYOFFICE_ENABLED_SET=false
 ENV_OVERRIDE_ONLYOFFICE_PUBLIC_URL_SET=false
 ENV_OVERRIDE_ONLYOFFICE_BACKEND_URL_SET=false
 ENV_OVERRIDE_ONLYOFFICE_JWT_SECRET_SET=false
+PREFER_ENV_FILE_FOR_ONLYOFFICE=false
+
+case "${X_FINANCIAL_PREFER_ENV_FILE:-false}" in
+    1|true|TRUE|yes|YES|on|ON)
+        PREFER_ENV_FILE_FOR_ONLYOFFICE=true
+        ;;
+esac
 
 if [ "${SERVER_HOST+x}" = x ]; then
     ENV_OVERRIDE_SERVER_HOST_SET=true
@@ -110,22 +117,22 @@ if [ "${DATABASE_URL+x}" = x ]; then
     ENV_OVERRIDE_DATABASE_URL="$DATABASE_URL"
 fi
 
-if [ "${ONLYOFFICE_ENABLED+x}" = x ]; then
+if [ "$PREFER_ENV_FILE_FOR_ONLYOFFICE" != true ] && [ "${ONLYOFFICE_ENABLED+x}" = x ]; then
     ENV_OVERRIDE_ONLYOFFICE_ENABLED_SET=true
     ENV_OVERRIDE_ONLYOFFICE_ENABLED="$ONLYOFFICE_ENABLED"
 fi
 
-if [ "${ONLYOFFICE_PUBLIC_URL+x}" = x ]; then
+if [ "$PREFER_ENV_FILE_FOR_ONLYOFFICE" != true ] && [ "${ONLYOFFICE_PUBLIC_URL+x}" = x ]; then
     ENV_OVERRIDE_ONLYOFFICE_PUBLIC_URL_SET=true
     ENV_OVERRIDE_ONLYOFFICE_PUBLIC_URL="$ONLYOFFICE_PUBLIC_URL"
 fi
 
-if [ "${ONLYOFFICE_BACKEND_URL+x}" = x ]; then
+if [ "$PREFER_ENV_FILE_FOR_ONLYOFFICE" != true ] && [ "${ONLYOFFICE_BACKEND_URL+x}" = x ]; then
     ENV_OVERRIDE_ONLYOFFICE_BACKEND_URL_SET=true
     ENV_OVERRIDE_ONLYOFFICE_BACKEND_URL="$ONLYOFFICE_BACKEND_URL"
 fi
 
-if [ "${ONLYOFFICE_JWT_SECRET+x}" = x ]; then
+if [ "$PREFER_ENV_FILE_FOR_ONLYOFFICE" != true ] && [ "${ONLYOFFICE_JWT_SECRET+x}" = x ]; then
     ENV_OVERRIDE_ONLYOFFICE_JWT_SECRET_SET=true
     ENV_OVERRIDE_ONLYOFFICE_JWT_SECRET="$ONLYOFFICE_JWT_SECRET"
 fi

server/src/app/core/config.py

@@ -1,22 +1,32 @@
-from __future__ import annotations
+from __future__ import annotations
-
+
-from functools import lru_cache
+from os import environ
-from os import environ
+from pathlib import Path
-from pathlib import Path
+
-
+from dotenv import dotenv_values
-from pydantic import Field
+from pydantic import Field
-from pydantic_settings import BaseSettings, SettingsConfigDict
+from pydantic_settings import BaseSettings, SettingsConfigDict
-
+
-SERVER_DIR = Path(__file__).resolve().parents[3]
+SERVER_DIR = Path(__file__).resolve().parents[3]
-ROOT_DIR = SERVER_DIR.parent
+ROOT_DIR = SERVER_DIR.parent
+DEFAULT_ENV_FILES = (ROOT_DIR / ".env", SERVER_DIR / ".env")
+ONLYOFFICE_FIELD_NAMES = {
+    "ONLYOFFICE_ENABLED": "onlyoffice_enabled",
+    "ONLYOFFICE_PUBLIC_URL": "onlyoffice_public_url",
+    "ONLYOFFICE_BACKEND_URL": "onlyoffice_backend_url",
+    "ONLYOFFICE_JWT_SECRET": "onlyoffice_jwt_secret",
+}
+
+_settings_cache: Settings | None = None
+_settings_cache_signature: tuple[tuple[str, bool, int | None, int | None], ...] | None = None
 
 
-class Settings(BaseSettings):
+class Settings(BaseSettings):
-    model_config = SettingsConfigDict(
+    model_config = SettingsConfigDict(
-        env_file=(ROOT_DIR / ".env", SERVER_DIR / ".env"),
+        env_file=DEFAULT_ENV_FILES,
-        env_file_encoding="utf-8",
+        env_file_encoding="utf-8",
-        extra="ignore",
+        extra="ignore",
-    )
+    )
 
     app_name: str = Field(default="X-Financial Server", alias="APP_NAME")
     app_env: str = Field(default="local", alias="APP_ENV")
@@ -73,16 +83,80 @@ class Settings(BaseSettings):
         if not path.is_absolute():
             path = SERVER_DIR / path
         return path.resolve()
-
+
-
+def _resolve_env_files() -> tuple[Path, ...]:
-@lru_cache
+    env_files = Settings.model_config.get("env_file") or ()
-def get_settings() -> Settings:
+    return tuple(Path(item) for item in env_files)
-    return Settings()
+
-
+
-
+def _build_settings_signature() -> tuple[tuple[str, bool, int | None, int | None], ...]:
-def refresh_settings(updated_values: dict[str, str]) -> Settings:
+    signature: list[tuple[str, bool, int | None, int | None]] = []
-    for key, value in updated_values.items():
+
-        environ[key] = value
+    for env_file in _resolve_env_files():
-
+        if not env_file.exists():
-    get_settings.cache_clear()
+            signature.append((str(env_file), False, None, None))
-    return get_settings()
+            continue
+
+        stat = env_file.stat()
+        signature.append((str(env_file), True, stat.st_mtime_ns, stat.st_size))
+
+    return tuple(signature)
+
+
+def _parse_onlyoffice_enabled(value: object) -> bool:
+    return str(value).strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _load_onlyoffice_env_file_overrides() -> dict[str, object]:
+    overrides: dict[str, object] = {}
+
+    for env_file in _resolve_env_files():
+        if not env_file.exists():
+            continue
+
+        values = dotenv_values(env_file)
+        for alias, field_name in ONLYOFFICE_FIELD_NAMES.items():
+            if alias not in values:
+                continue
+
+            value = values[alias]
+            if field_name == "onlyoffice_enabled":
+                overrides[field_name] = _parse_onlyoffice_enabled(value)
+            else:
+                overrides[field_name] = "" if value is None else str(value)
+
+    return overrides
+
+
+def _clear_settings_cache() -> None:
+    global _settings_cache, _settings_cache_signature
+
+    _settings_cache = None
+    _settings_cache_signature = None
+
+
+def get_settings() -> Settings:
+    global _settings_cache, _settings_cache_signature
+
+    signature = _build_settings_signature()
+    if _settings_cache is None or _settings_cache_signature != signature:
+        settings = Settings()
+        onlyoffice_overrides = _load_onlyoffice_env_file_overrides()
+        if onlyoffice_overrides:
+            settings = settings.model_copy(update=onlyoffice_overrides)
+
+        _settings_cache = settings
+        _settings_cache_signature = signature
+
+    return _settings_cache
+
+
+get_settings.cache_clear = _clear_settings_cache  # type: ignore[attr-defined]
+
+
+def refresh_settings(updated_values: dict[str, str]) -> Settings:
+    for key, value in updated_values.items():
+        environ[key] = value
+
+    get_settings.cache_clear()
+    return get_settings()

server/src/app/services/knowledge.py

@@ -232,19 +232,43 @@ class KnowledgeService:
 
         return file_path, entry["mime_type"], entry["original_name"]
 
-    def build_onlyoffice_config(
+    def build_onlyoffice_config(
-        self,
+        self,
-        document_id: str,
+        document_id: str,
-        current_user: CurrentUserContext,
+        current_user: CurrentUserContext,
-    ) -> KnowledgeOnlyOfficeConfigRead:
+    ) -> KnowledgeOnlyOfficeConfigRead:
-        self.ensure_library_ready()
+        self.ensure_library_ready()
-        settings = get_settings()
+        settings = get_settings()
-        if not settings.onlyoffice_enabled:
+        if not settings.onlyoffice_enabled:
-            raise ValueError("ONLYOFFICE 预览未启用。")
+            logger.warning(
-        if not settings.onlyoffice_public_url or not settings.onlyoffice_backend_url:
+                "ONLYOFFICE disabled in runtime config doc=%s enabled=%s public_url=%s backend_url=%s jwt_set=%s",
-            raise ValueError("ONLYOFFICE 地址配置不完整。")
+                document_id,
-        if not settings.onlyoffice_jwt_secret:
+                settings.onlyoffice_enabled,
-            raise ValueError("ONLYOFFICE JWT 密钥未配置。")
+                settings.onlyoffice_public_url,
+                settings.onlyoffice_backend_url,
+                bool(settings.onlyoffice_jwt_secret),
+            )
+            raise ValueError("ONLYOFFICE 预览未启用。")
+        if not settings.onlyoffice_public_url or not settings.onlyoffice_backend_url:
+            logger.warning(
+                "ONLYOFFICE config incomplete doc=%s enabled=%s public_url=%s backend_url=%s jwt_set=%s",
+                document_id,
+                settings.onlyoffice_enabled,
+                settings.onlyoffice_public_url,
+                settings.onlyoffice_backend_url,
+                bool(settings.onlyoffice_jwt_secret),
+            )
+            raise ValueError("ONLYOFFICE 地址配置不完整。")
+        if not settings.onlyoffice_jwt_secret:
+            logger.warning(
+                "ONLYOFFICE JWT missing doc=%s enabled=%s public_url=%s backend_url=%s jwt_set=%s",
+                document_id,
+                settings.onlyoffice_enabled,
+                settings.onlyoffice_public_url,
+                settings.onlyoffice_backend_url,
+                bool(settings.onlyoffice_jwt_secret),
+            )
+            raise ValueError("ONLYOFFICE JWT 密钥未配置。")
 
         index = self._load_index()
         entry = self._require_entry(index, document_id)
@@ -263,42 +287,41 @@ class KnowledgeService:
         callback_url = (
             f"{backend_base_url}{settings.api_v1_prefix}/knowledge/documents/{document_id}/onlyoffice/callback"
         )
-        can_edit = current_user.is_admin or "manager" in current_user.role_codes
+        document_key = self._build_onlyoffice_document_key(entry)
-        document_key = self._build_onlyoffice_document_key(entry)
+
-
+        config: dict[str, Any] = {
-        config: dict[str, Any] = {
+            "documentType": document_type,
-            "documentType": document_type,
+            "document": {
-            "document": {
                 "fileType": extension,
                 "key": document_key,
-                "title": entry["original_name"],
+                "title": entry["original_name"],
-                "url": document_url,
+                "url": document_url,
-                "permissions": {
+                "permissions": {
-                    "download": True,
+                    "download": True,
-                    "edit": can_edit,
+                    "edit": False,
-                    "print": True,
+                    "print": True,
-                    "copy": True,
+                    "copy": True,
+                },
+            },
+            "editorConfig": {
+                "mode": "view",
+                "lang": "zh-CN",
+                "callbackUrl": callback_url,
+                "user": {
+                    "id": current_user.username,
+                    "name": current_user.name,
                 },
-            },
+                "customization": {
-            "editorConfig": {
+                    "compactHeader": True,
-                "mode": "edit" if can_edit else "view",
+                    "compactToolbar": True,
-                "lang": "zh-CN",
+                    "toolbarNoTabs": False,
-                "callbackUrl": callback_url,
+                    "autosave": False,
-                "user": {
+                    "forcesave": False,
-                    "id": current_user.username,
+                },
-                    "name": current_user.name,
+            },
-                },
+            "width": "100%",
-                "customization": {
+            "height": "100%",
-                    "compactHeader": True,
+        }
-                    "compactToolbar": True,
-                    "toolbarNoTabs": False,
-                    "autosave": can_edit,
-                    "forcesave": can_edit,
-                },
-            },
-            "width": "100%",
-            "height": "100%",
-        }
         config["token"] = jwt.encode(config, settings.onlyoffice_jwt_secret, algorithm="HS256")
 
         return KnowledgeOnlyOfficeConfigRead(

server/src/x_financial_server.egg-info/PKG-INFO

@@ -9,6 +9,7 @@ Requires-Dist: uvicorn[standard]<1.0.0,>=0.30.0
 Requires-Dist: sqlalchemy<3.0.0,>=2.0.36
 Requires-Dist: alembic<2.0.0,>=1.14.0
 Requires-Dist: psycopg[binary]<4.0.0,>=3.2.0
+Requires-Dist: PyJWT<3.0.0,>=2.9.0
 Requires-Dist: pydantic-settings<3.0.0,>=2.6.0
 Requires-Dist: python-dotenv<2.0.0,>=1.0.1
 Requires-Dist: email-validator<3.0.0,>=2.2.0

server/src/x_financial_server.egg-info/SOURCES.txt

@@ -12,6 +12,7 @@ src/app/api/v1/endpoints/auth.py
 src/app/api/v1/endpoints/bootstrap.py
 src/app/api/v1/endpoints/employees.py
 src/app/api/v1/endpoints/health.py
+src/app/api/v1/endpoints/knowledge.py
 src/app/api/v1/endpoints/reimbursements.py
 src/app/api/v1/endpoints/settings.py
 src/app/core/__init__.py
@@ -45,12 +46,14 @@ src/app/schemas/__init__.py
 src/app/schemas/auth.py
 src/app/schemas/bootstrap.py
 src/app/schemas/employee.py
+src/app/schemas/knowledge.py
 src/app/schemas/reimbursement.py
 src/app/schemas/settings.py
 src/app/services/__init__.py
 src/app/services/auth.py
 src/app/services/employee.py
 src/app/services/employee_seed.py
+src/app/services/knowledge.py
 src/app/services/model_connectivity.py
 src/app/services/reimbursement.py
 src/app/services/settings.py
@@ -62,5 +65,6 @@ src/x_financial_server.egg-info/top_level.txt
 tests/test_auth_service.py
 tests/test_employee_service.py
 tests/test_imports.py
+tests/test_server_start_dependencies.py
 tests/test_settings_persistence.py
 tests/test_settings_service.py

server/src/x_financial_server.egg-info/requires.txt

@@ -3,6 +3,7 @@ uvicorn[standard]<1.0.0,>=0.30.0
 sqlalchemy<3.0.0,>=2.0.36
 alembic<2.0.0,>=1.14.0
 psycopg[binary]<4.0.0,>=3.2.0
+PyJWT<3.0.0,>=2.9.0
 pydantic-settings<3.0.0,>=2.6.0
 python-dotenv<2.0.0,>=1.0.1
 email-validator<3.0.0,>=2.2.0

server/storage/knowledge/.index.json

@@ -14,6 +14,34 @@
       "updated_at": "2026-05-09T05:46:24.699125+00:00",
       "uploaded_by": "admin",
       "version_number": 1
+    },
+    {
+      "id": "6cad2936d57242d29d26f6fbb6314767",
+      "folder": "财务知识库",
+      "original_name": "2508.19855v3.pdf",
+      "stored_name": "6cad2936d57242d29d26f6fbb6314767__2508.19855v3.pdf",
+      "mime_type": "application/pdf",
+      "extension": "pdf",
+      "size_bytes": 4097809,
+      "sha256": "9061363b164aaba132454e239ecc107076c81f61ecab1eb39cb43405d481e46a",
+      "created_at": "2026-05-09T06:06:51.631071+00:00",
+      "updated_at": "2026-05-09T06:06:51.631071+00:00",
+      "uploaded_by": "admin",
+      "version_number": 1
+    },
+    {
+      "id": "b01fe587d3d941f0a25d500751b27094",
+      "folder": "财务知识库",
+      "original_name": "面向财务领域的大语言模型 Fin-R1 研究内容与实施计划 (1).docx",
+      "stored_name": "b01fe587d3d941f0a25d500751b27094__面向财务领域的大语言模型 Fin-R1 研究内容与实施计划 (1).docx",
+      "mime_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+      "extension": "docx",
+      "size_bytes": 35521,
+      "sha256": "b300ba9c4c5bb03f4cbb27b52eea1932d1594398ae7b0f0c51c6c250deaceab4",
+      "created_at": "2026-05-09T06:07:10.525556+00:00",
+      "updated_at": "2026-05-09T07:17:28.581707+00:00",
+      "uploaded_by": "admin",
+      "version_number": 3
     }
   ]
 }

server/tests/test_config_settings_reload.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import os
+
+from app.core.config import Settings, get_settings
+
+
+def test_get_settings_refreshes_when_env_file_changes(tmp_path, monkeypatch) -> None:
+    env_file = tmp_path / ".env"
+    env_file.write_text("ONLYOFFICE_ENABLED=false\n", encoding="utf-8")
+
+    original_env_file = Settings.model_config.get("env_file")
+    monkeypatch.setitem(Settings.model_config, "env_file", (env_file,))
+    get_settings.cache_clear()
+
+    try:
+        first = get_settings()
+        assert first.onlyoffice_enabled is False
+
+        env_file.write_text("ONLYOFFICE_ENABLED=true\n", encoding="utf-8")
+        os.utime(env_file, None)
+
+        second = get_settings()
+        assert second.onlyoffice_enabled is True
+    finally:
+        monkeypatch.setitem(Settings.model_config, "env_file", original_env_file)
+        get_settings.cache_clear()
+
+
+def test_onlyoffice_values_prefer_env_file_over_inherited_environment(tmp_path, monkeypatch) -> None:
+    env_file = tmp_path / ".env"
+    env_file.write_text(
+        "\n".join(
+            [
+                "ONLYOFFICE_ENABLED=true",
+                "ONLYOFFICE_PUBLIC_URL=http://10.10.10.122:8082",
+                "ONLYOFFICE_BACKEND_URL=http://main:8000",
+                "ONLYOFFICE_JWT_SECRET=change-me-onlyoffice",
+            ]
+        )
+        + "\n",
+        encoding="utf-8",
+    )
+
+    original_env_file = Settings.model_config.get("env_file")
+    monkeypatch.setitem(Settings.model_config, "env_file", (env_file,))
+    monkeypatch.setenv("ONLYOFFICE_ENABLED", "false")
+    monkeypatch.setenv("ONLYOFFICE_PUBLIC_URL", "http://127.0.0.1:8082")
+    get_settings.cache_clear()
+
+    try:
+        settings = get_settings()
+
+        assert settings.onlyoffice_enabled is True
+        assert settings.onlyoffice_public_url == "http://10.10.10.122:8082"
+        assert settings.onlyoffice_backend_url == "http://main:8000"
+        assert settings.onlyoffice_jwt_secret == "change-me-onlyoffice"
+    finally:
+        monkeypatch.setitem(Settings.model_config, "env_file", original_env_file)
+        get_settings.cache_clear()

server/tests/test_env_file_precedence.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+from pathlib import Path
+import os
+import subprocess
+
+
+def _run_script_prefix(
+    tmp_path: Path,
+    relative_script_path: str,
+    env_file_content: str,
+    env: dict[str, str],
+    output_vars: list[str],
+) -> subprocess.CompletedProcess[str]:
+    project_dir = tmp_path / "project"
+    script_source = Path(__file__).resolve().parents[2] / relative_script_path
+    script_copy = project_dir / relative_script_path
+    script_copy.parent.mkdir(parents=True, exist_ok=True)
+    script_copy.write_text(script_source.read_text(encoding="utf-8"), encoding="utf-8")
+    (project_dir / ".env").write_text(env_file_content, encoding="utf-8")
+
+    script_prefix = script_copy.read_text(encoding="utf-8").split('case "$MODE" in', 1)[0]
+    print_lines = "\n".join(f'printf "{name}=%s\\n" "${{{name}:-}}"' for name in output_vars)
+    command = f"""{script_prefix}
+{print_lines}
+"""
+
+    return subprocess.run(
+        ["bash", "-c", command, str(script_copy)],
+        capture_output=True,
+        text=True,
+        env={**os.environ, **env, "MODE": "test"},
+        cwd=script_copy.parent,
+        check=False,
+    )
+
+
+def test_server_start_can_prefer_env_file_over_inherited_onlyoffice_values(tmp_path: Path) -> None:
+    result = _run_script_prefix(
+        tmp_path,
+        "server/server_start.sh",
+        env_file_content=(
+            "ONLYOFFICE_ENABLED=true\n"
+            "ONLYOFFICE_PUBLIC_URL=http://10.10.10.122:8082\n"
+            "ONLYOFFICE_BACKEND_URL=http://main:8000\n"
+            "ONLYOFFICE_JWT_SECRET=change-me-onlyoffice\n"
+        ),
+        env={
+            "ONLYOFFICE_ENABLED": "false",
+            "ONLYOFFICE_PUBLIC_URL": "http://127.0.0.1:8082",
+            "X_FINANCIAL_PREFER_ENV_FILE": "true",
+        },
+        output_vars=["ONLYOFFICE_ENABLED", "ONLYOFFICE_PUBLIC_URL"],
+    )
+
+    assert result.returncode == 0, result.stderr
+    assert "ONLYOFFICE_ENABLED=true" in result.stdout
+    assert "ONLYOFFICE_PUBLIC_URL=http://10.10.10.122:8082" in result.stdout
+
+
+def test_root_start_can_prefer_env_file_over_inherited_onlyoffice_values(tmp_path: Path) -> None:
+    result = _run_script_prefix(
+        tmp_path,
+        "start.sh",
+        env_file_content=(
+            "ONLYOFFICE_ENABLED=true\n"
+            "ONLYOFFICE_PUBLIC_URL=http://10.10.10.122:8082\n"
+            "ONLYOFFICE_BACKEND_URL=http://main:8000\n"
+            "ONLYOFFICE_JWT_SECRET=change-me-onlyoffice\n"
+        ),
+        env={
+            "ONLYOFFICE_ENABLED": "false",
+            "ONLYOFFICE_PUBLIC_URL": "http://127.0.0.1:8082",
+            "X_FINANCIAL_PREFER_ENV_FILE": "true",
+        },
+        output_vars=["ONLYOFFICE_ENABLED", "ONLYOFFICE_PUBLIC_URL"],
+    )
+
+    assert result.returncode == 0, result.stderr
+    assert "ONLYOFFICE_ENABLED=true" in result.stdout
+    assert "ONLYOFFICE_PUBLIC_URL=http://10.10.10.122:8082" in result.stdout

server/tests/test_knowledge_onlyoffice_config.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from app.api.deps import CurrentUserContext
+from app.core.config import Settings, get_settings
+from app.services.knowledge import KnowledgeService
+
+
+def test_onlyoffice_config_is_read_only_for_admin_users(tmp_path, monkeypatch) -> None:
+    env_file = tmp_path / ".env"
+    env_file.write_text(
+        "\n".join(
+            [
+                "ONLYOFFICE_ENABLED=true",
+                "ONLYOFFICE_PUBLIC_URL=http://10.10.10.122:8082",
+                "ONLYOFFICE_BACKEND_URL=http://main:8000",
+                "ONLYOFFICE_JWT_SECRET=change-me-onlyoffice",
+            ]
+        )
+        + "\n",
+        encoding="utf-8",
+    )
+    original_env_file = Settings.model_config.get("env_file")
+    monkeypatch.setitem(Settings.model_config, "env_file", (env_file,))
+    get_settings.cache_clear()
+
+    try:
+        service = KnowledgeService(storage_root=tmp_path)
+        service.ensure_library_ready()
+
+        document_id = "readonly-docx"
+        folder = "制度政策"
+        stored_name = f"{document_id}__制度预览.docx"
+        target_path = tmp_path / "knowledge" / folder / stored_name
+        target_path.write_bytes(b"fake-docx-content")
+
+        current_user = CurrentUserContext(
+            username="admin",
+            name="管理员",
+            role_codes=["manager"],
+            is_admin=True,
+        )
+
+        config = service.build_onlyoffice_config(document_id, current_user)
+        permissions = config.config["document"]["permissions"]
+        customization = config.config["editorConfig"]["customization"]
+
+        assert config.documentServerUrl == "http://10.10.10.122:8082"
+        assert config.config["editorConfig"]["mode"] == "view"
+        assert permissions["edit"] is False
+        assert permissions["download"] is True
+        assert customization["autosave"] is False
+        assert customization["forcesave"] is False
+    finally:
+        monkeypatch.setitem(Settings.model_config, "env_file", original_env_file)
+        get_settings.cache_clear()

start.sh

@@ -42,6 +42,13 @@ ENV_OVERRIDE_ONLYOFFICE_ENABLED_SET=false
 ENV_OVERRIDE_ONLYOFFICE_PUBLIC_URL_SET=false
 ENV_OVERRIDE_ONLYOFFICE_BACKEND_URL_SET=false
 ENV_OVERRIDE_ONLYOFFICE_JWT_SECRET_SET=false
+PREFER_ENV_FILE_FOR_ONLYOFFICE=false
+
+case "${X_FINANCIAL_PREFER_ENV_FILE:-false}" in
+  1|true|TRUE|yes|YES|on|ON)
+    PREFER_ENV_FILE_FOR_ONLYOFFICE=true
+    ;;
+esac
 
 if [ "${WEB_HOST+x}" = x ]; then
   ENV_OVERRIDE_WEB_HOST_SET=true
@@ -53,22 +60,22 @@ if [ "${SERVER_HOST+x}" = x ]; then
   ENV_OVERRIDE_SERVER_HOST="$SERVER_HOST"
 fi
 
-if [ "${ONLYOFFICE_ENABLED+x}" = x ]; then
+if [ "$PREFER_ENV_FILE_FOR_ONLYOFFICE" != true ] && [ "${ONLYOFFICE_ENABLED+x}" = x ]; then
   ENV_OVERRIDE_ONLYOFFICE_ENABLED_SET=true
   ENV_OVERRIDE_ONLYOFFICE_ENABLED="$ONLYOFFICE_ENABLED"
 fi
 
-if [ "${ONLYOFFICE_PUBLIC_URL+x}" = x ]; then
+if [ "$PREFER_ENV_FILE_FOR_ONLYOFFICE" != true ] && [ "${ONLYOFFICE_PUBLIC_URL+x}" = x ]; then
   ENV_OVERRIDE_ONLYOFFICE_PUBLIC_URL_SET=true
   ENV_OVERRIDE_ONLYOFFICE_PUBLIC_URL="$ONLYOFFICE_PUBLIC_URL"
 fi
 
-if [ "${ONLYOFFICE_BACKEND_URL+x}" = x ]; then
+if [ "$PREFER_ENV_FILE_FOR_ONLYOFFICE" != true ] && [ "${ONLYOFFICE_BACKEND_URL+x}" = x ]; then
   ENV_OVERRIDE_ONLYOFFICE_BACKEND_URL_SET=true
   ENV_OVERRIDE_ONLYOFFICE_BACKEND_URL="$ONLYOFFICE_BACKEND_URL"
 fi
 
-if [ "${ONLYOFFICE_JWT_SECRET+x}" = x ]; then
+if [ "$PREFER_ENV_FILE_FOR_ONLYOFFICE" != true ] && [ "${ONLYOFFICE_JWT_SECRET+x}" = x ]; then
   ENV_OVERRIDE_ONLYOFFICE_JWT_SECRET_SET=true
   ENV_OVERRIDE_ONLYOFFICE_JWT_SECRET="$ONLYOFFICE_JWT_SECRET"
 fi

web/src/assets/styles/views/policies-view.css

@@ -5,22 +5,20 @@
   animation: fadeUp 220ms var(--ease) both;
 }
 
-.knowledge-grid {
+.knowledge-grid {
-  height: 100%;
+  height: 100%;
-  min-height: 0;
+  min-height: 0;
-  display: grid;
+  display: grid;
-  grid-template-columns: minmax(0, 1fr) 0;
+  grid-template-columns: minmax(0, 1fr);
-  gap: 0;
+  gap: 0;
-  transition: grid-template-columns 320ms var(--ease), gap 320ms var(--ease);
+}
-}
+
-
+.knowledge-grid.has-preview {
-.knowledge-grid.has-preview {
+  grid-template-columns: minmax(0, 1fr);
-  grid-template-columns: minmax(560px, 1fr) minmax(420px, 0.82fr);
+}
-  gap: 16px;
+
-}
+.knowledge-main,
-
+.preview-column {
-.knowledge-main,
-.preview-column {
   min-width: 0;
   min-height: 0;
 }
@@ -470,17 +468,11 @@ th {
   color: #fff;
 }
 
-.preview-column {
+.preview-panel {
-  min-width: 0;
+  height: 100%;
-  min-height: 0;
+  min-height: 0;
-  overflow: hidden;
+  display: grid;
-}
+  grid-template-rows: auto minmax(0, 1fr);
-
-.preview-panel {
-  height: 100%;
-  min-height: 0;
-  display: grid;
-  grid-template-rows: auto minmax(0, 1fr);
   padding: 20px 22px;
   overflow: hidden;
 }
@@ -555,13 +547,46 @@ th {
   line-height: 1.5;
 }
 
-.preview-viewer {
+.preview-viewer {
-  min-height: 0;
+  min-height: 0;
-  margin-top: 18px;
+  margin-top: 18px;
-}
+  display: grid;
-
+}
-.preview-status {
+
-  display: grid;
+.preview-modal-overlay {
+  position: fixed;
+  inset: 0;
+  z-index: 2000;
+  display: grid;
+  place-items: center;
+  padding: 3vh 2vw;
+  background:
+    radial-gradient(circle at top, rgba(37, 99, 235, 0.12), transparent 32%),
+    rgba(15, 23, 42, 0.56);
+  backdrop-filter: blur(10px);
+}
+
+.preview-modal-shell {
+  width: min(96vw, 1600px);
+  height: min(94vh, 1180px);
+  min-height: 0;
+}
+
+.preview-modal-panel {
+  height: 100%;
+  border-radius: 24px;
+  box-shadow: 0 30px 90px rgba(15, 23, 42, 0.24);
+}
+
+.preview-modal-panel:focus {
+  outline: none;
+  box-shadow:
+    0 0 0 4px rgba(96, 165, 250, 0.22),
+    0 30px 90px rgba(15, 23, 42, 0.24);
+}
+
+.preview-status {
+  display: grid;
   place-items: center;
   min-height: 180px;
   padding: 24px;
@@ -580,21 +605,22 @@ th {
   color: #dc2626;
 }
 
-.preview-embed-wrap,
+.preview-embed-wrap,
-.preview-image-wrap {
+.preview-image-wrap {
-  min-height: 0;
+  min-height: 0;
-  overflow: hidden;
+  height: 100%;
-  border: 1px solid #edf2f7;
+  overflow: hidden;
-  border-radius: 12px;
+  border: 1px solid #edf2f7;
-  background: #fff;
+  border-radius: 12px;
+  background: #fff;
 }
 
-.preview-embed {
+.preview-embed {
-  width: 100%;
+  width: 100%;
-  height: 100%;
+  height: 100%;
-  min-height: 560px;
+  min-height: 0;
-  border: 0;
+  border: 0;
-}
+}
 
 .preview-image-wrap {
   display: grid;
@@ -608,25 +634,38 @@ th {
   object-fit: contain;
 }
 
-.onlyoffice-preview-wrap {
+.onlyoffice-preview-wrap {
-  min-height: 0;
+  position: relative;
-  overflow: hidden;
+  min-height: 0;
-  border: 1px solid #dbe4ee;
+  height: 100%;
-  border-radius: 12px;
+  overflow: hidden;
-  background: #fff;
+  border: 1px solid #dbe4ee;
-}
+  border-radius: 12px;
+  background: #fff;
+}
+
+.onlyoffice-preview-host {
+  width: 100%;
+  height: 100%;
+  min-height: 720px;
+}
+
+.preview-status-overlay {
+  position: absolute;
+  inset: 0;
+  margin: 0;
+  border: 0;
+  border-radius: 0;
+  background: rgba(248, 250, 252, 0.92);
+}
 
-.onlyoffice-preview-host {
+.excel-preview-wrap {
-  width: 100%;
+  min-height: 0;
-  min-height: 720px;
+  height: 100%;
-}
+  overflow: hidden;
-
+  border: 1px solid #dbe4ee;
-.excel-preview-wrap {
+  border-radius: 12px;
-  min-height: 0;
+  background: #fff;
-  overflow: hidden;
-  border: 1px solid #dbe4ee;
-  border-radius: 12px;
-  background: #fff;
 }
 
 .excel-sheet-tabs {
@@ -707,13 +746,18 @@ th {
   border-bottom: 0;
 }
 
-.page-stage {
+.page-stage {
-  min-height: 0;
+  min-height: 0;
-  overflow: auto;
+  height: 100%;
-  display: grid;
+  overflow: auto;
-  gap: 20px;
+  display: grid;
-  padding-right: 6px;
+  gap: 20px;
-}
+  padding-right: 6px;
+  border: 1px solid #e2e8f0;
+  border-radius: 12px;
+  background: linear-gradient(180deg, #ffffff 0%, #f8fafc 100%);
+  padding: 18px 18px 18px 18px;
+}
 
 .page-sheet {
   display: grid;
@@ -807,16 +851,26 @@ th {
   line-height: 1.75;
 }
 
-.preview-panel-enter-active,
+.preview-modal-enter-active,
-.preview-panel-leave-active {
+.preview-modal-leave-active {
-  transition: opacity 240ms ease, transform 320ms var(--ease);
+  transition: opacity 220ms ease;
-}
+}
-
+
-.preview-panel-enter-from,
+.preview-modal-enter-active .preview-modal-shell,
-.preview-panel-leave-to {
+.preview-modal-leave-active .preview-modal-shell {
-  opacity: 0;
+  transition: transform 320ms var(--ease), opacity 220ms ease;
-  transform: translateX(24px) scale(0.98);
+}
-}
+
+.preview-modal-enter-from,
+.preview-modal-leave-to {
+  opacity: 0;
+}
+
+.preview-modal-enter-from .preview-modal-shell,
+.preview-modal-leave-to .preview-modal-shell {
+  opacity: 0;
+  transform: translateY(24px) scale(0.985);
+}
 
 @keyframes previewSheetIn {
   from {
@@ -829,15 +883,9 @@ th {
   }
 }
 
-@media (max-width: 1320px) {
+@media (max-width: 1080px) {
-  .knowledge-grid.has-preview {
+  .knowledge-grid,
-    grid-template-columns: minmax(0, 1fr) minmax(360px, 0.78fr);
+  .knowledge-grid.has-preview {
-  }
-}
-
-@media (max-width: 1080px) {
-  .knowledge-grid,
-  .knowledge-grid.has-preview {
     grid-template-columns: 1fr;
     gap: 16px;
     overflow-y: auto;
@@ -854,9 +902,9 @@ th {
   }
 }
 
-@media (max-width: 760px) {
+@media (max-width: 760px) {
-  .panel-title,
+  .panel-title,
-  .preview-head,
+  .preview-head,
   .viewer-toolbar {
     flex-direction: column;
     align-items: stretch;
@@ -872,9 +920,31 @@ th {
     justify-items: stretch;
   }
 
-  .pager,
+  .pager,
-  .page-size-wrap,
+  .page-size-wrap,
-  .page-size {
+  .page-size {
-    justify-self: stretch;
+    justify-self: stretch;
-  }
+  }
-}
+
+  .preview-modal-overlay {
+    padding: 8px;
+  }
+
+  .preview-modal-shell {
+    width: calc(100vw - 16px);
+    height: calc(100vh - 16px);
+  }
+
+  .preview-modal-panel {
+    border-radius: 18px;
+    padding: 16px;
+  }
+
+  .preview-head {
+    padding-bottom: 12px;
+  }
+
+  .preview-viewer {
+    margin-top: 14px;
+  }
+}

web/src/views/PoliciesView.vue

@@ -1,15 +1,15 @@
 <template>
-  <section class="knowledge-page">
+  <section class="knowledge-page">
-    <div class="knowledge-grid" :class="{ 'has-preview': selectedDocument }">
+    <div class="knowledge-grid" :class="{ 'has-preview': previewLayoutState.usesSplitLayout }">
-      <section class="knowledge-main">
+      <section class="knowledge-main">
-        <article class="library-panel panel">
+        <article class="library-panel panel">
-          <header class="panel-title">
+          <header class="panel-title">
-            <div>
+            <div>
-              <h2>文档库 / 文件夹</h2>
+              <h2>文档库 / 文件夹</h2>
-              <p>默认展示文件列表，点击具体文件后可在右侧展开预览。</p>
+              <p>默认展示文件列表，点击具体文件后以弹窗方式展开预览。</p>
-            </div>
+            </div>
-            <label class="file-search">
+            <label class="file-search">
-              <i class="mdi mdi-magnify"></i>
+              <i class="mdi mdi-magnify"></i>
               <input v-model="documentSearch" type="search" placeholder="搜索当前文件夹内文件" />
             </label>
           </header>
@@ -159,18 +159,29 @@
               </footer>
             </section>
           </div>
-        </article>
+        </article>
-      </section>
+      </section>
-
+      <Teleport to="body">
-      <Transition name="preview-panel">
+        <Transition name="preview-modal">
-        <aside v-if="selectedDocument" class="preview-column">
+          <div
-          <article class="preview-panel panel">
+            v-if="previewLayoutState.isPreviewModalOpen"
-            <header class="preview-head">
+            class="preview-modal-overlay"
-              <div class="preview-copy">
+            role="presentation"
-                <h2>{{ selectedDocument.name }}</h2>
+            @click.self="closePreview"
-                <p class="preview-summary-line">
+          >
-                  <span v-for="part in previewMetaLine" :key="part">{{ part }}</span>
+            <aside class="preview-modal-shell" role="dialog" aria-modal="true" aria-labelledby="knowledge-preview-title">
-                </p>
+              <article
+                ref="previewDialogPanel"
+                class="preview-panel preview-modal-panel panel"
+                tabindex="-1"
+                @click.stop
+              >
+            <header class="preview-head">
+              <div class="preview-copy">
+                <h2 id="knowledge-preview-title">{{ selectedDocument.name }}</h2>
+                <p class="preview-summary-line">
+                  <span v-for="part in previewMetaLine" :key="part">{{ part }}</span>
+                </p>
                 <div v-if="previewSecondaryMetaLine.length" class="preview-secondary-line">
                   <span v-for="part in previewSecondaryMetaLine" :key="part">{{ part }}</span>
                 </div>
@@ -185,22 +196,30 @@
                   <i class="mdi mdi-close"></i>
                 </button>
               </div>
-            </header>
+            </header>
-
+
-            <div class="preview-viewer">
+            <div class="preview-viewer">
-              <div v-if="previewLoading" class="preview-status">正在加载预览...</div>
+              <div v-if="shouldRenderOnlyOffice" class="onlyoffice-preview-wrap">
-              <div v-else-if="previewError" class="preview-status error">{{ previewError }}</div>
+                <div
+                  v-if="shouldRenderOnlyOfficeHostNode"
+                  :id="onlyOfficeHostId"
+                  class="onlyoffice-preview-host"
+                ></div>
+                <div v-if="onlyOfficeLoading" class="preview-status preview-status-overlay">
+                  正在加载 ONLYOFFICE 预览...
+                </div>
+                <div v-else-if="onlyOfficeError" class="preview-status error preview-status-overlay">
+                  {{ onlyOfficeError }}
+                </div>
+              </div>
+              <div v-else-if="previewLoading" class="preview-status">正在加载预览...</div>
+              <div v-else-if="previewError" class="preview-status error">{{ previewError }}</div>
               <div v-else-if="previewMode === 'pdf' && previewBlobUrl" class="preview-embed-wrap">
                 <iframe :src="previewBlobUrl" class="preview-embed" title="PDF 预览"></iframe>
               </div>
               <div v-else-if="previewMode === 'image' && previewBlobUrl" class="preview-image-wrap">
                 <img :src="previewBlobUrl" :alt="selectedDocument.name" class="preview-image" />
               </div>
-              <div v-else-if="shouldUseOnlyOffice" class="onlyoffice-preview-wrap">
-                <div v-if="onlyOfficeLoading" class="preview-status">正在加载 ONLYOFFICE 预览...</div>
-                <div v-else-if="onlyOfficeError" class="preview-status error">{{ onlyOfficeError }}</div>
-                <div v-else :id="onlyOfficeHostId" class="onlyoffice-preview-host"></div>
-              </div>
               <div v-else-if="previewMode === 'table'" class="excel-preview-wrap">
                 <div v-if="selectedDocument.previewPages.length > 1" class="excel-sheet-tabs" role="tablist" aria-label="Excel 工作表页签">
                   <button
@@ -249,15 +268,17 @@
                 </article>
                 <div v-if="!selectedDocument.previewPages.length" class="preview-status">
                   当前文件暂未生成结构化预览，请下载后查看。
-                </div>
+                </div>
-              </div>
+              </div>
-            </div>
+            </div>
-          </article>
+              </article>
-        </aside>
+            </aside>
-      </Transition>
+          </div>
-    </div>
+        </Transition>
-  </section>
+      </Teleport>
-</template>
+    </div>
+  </section>
+</template>
 
 <script src="./scripts/PoliciesView.js"></script>
 

web/src/views/scripts/PoliciesView.js

@@ -17,7 +17,14 @@ import {
   buildPreviewMetaLine,
   buildPreviewSecondaryMetaLine
 } from './policiesPreviewFormatters.js'
-import { canUseOnlyOfficePreview, resolveKnowledgePreviewMode } from './knowledgePreviewMode.js'
+import {
+  canUseOnlyOfficePreview,
+  resolveKnowledgePreviewMode,
+  shouldRenderOnlyOfficeHost,
+  shouldRenderOnlyOfficePreview
+} from './knowledgePreviewMode.js'
+import { resolveKnowledgePreviewLayoutState } from './knowledgePreviewLayout.js'
+import { buildOnlyOfficePreviewConfig } from './onlyOfficePreviewConfig.js'
 
 function triggerFileDownload(blob, filename) {
   const url = URL.createObjectURL(blob)
@@ -27,6 +34,43 @@ function triggerFileDownload(blob, filename) {
   anchor.click()
   URL.revokeObjectURL(url)
 }
+
+let bodyOverflowSnapshot = ''
+let bodyOverscrollBehaviorSnapshot = ''
+
+function setBodyScrollLocked(isLocked) {
+  if (typeof document === 'undefined') {
+    return
+  }
+
+  const { body } = document
+  if (!body) {
+    return
+  }
+
+  if (isLocked) {
+    if (body.dataset.knowledgePreviewLocked === 'true') {
+      return
+    }
+
+    bodyOverflowSnapshot = body.style.overflow
+    bodyOverscrollBehaviorSnapshot = body.style.overscrollBehavior
+    body.style.overflow = 'hidden'
+    body.style.overscrollBehavior = 'contain'
+    body.dataset.knowledgePreviewLocked = 'true'
+    return
+  }
+
+  if (body.dataset.knowledgePreviewLocked !== 'true') {
+    return
+  }
+
+  body.style.overflow = bodyOverflowSnapshot
+  body.style.overscrollBehavior = bodyOverscrollBehaviorSnapshot
+  delete body.dataset.knowledgePreviewLocked
+  bodyOverflowSnapshot = ''
+  bodyOverscrollBehaviorSnapshot = ''
+}
 
 export default {
   name: 'PoliciesView',
@@ -56,7 +100,9 @@ export default {
     const onlyOfficeAvailable = ref(false)
     const onlyOfficeEditor = ref(null)
     const onlyOfficeHostId = ref('knowledge-onlyoffice-preview')
+    const onlyOfficeReadyTimeoutId = ref(0)
     const currentPreviewPageIndex = ref(0)
+    const previewDialogPanel = ref(null)
 
     const isAdmin = computed(() => isManagerUser(currentUser.value))
     const uploadHint = computed(() =>
@@ -88,15 +134,31 @@ export default {
       return pages[currentPreviewPageIndex.value] || pages[0] || null
     })
     const previewMetaLine = computed(() => buildPreviewMetaLine(selectedDocument.value))
-    const previewSecondaryMetaLine = computed(() =>
+    const previewSecondaryMetaLine = computed(() =>
-      buildPreviewSecondaryMetaLine(selectedDocument.value, activePreviewPage.value)
+      buildPreviewSecondaryMetaLine(selectedDocument.value, activePreviewPage.value)
-    )
+    )
+    const previewLayoutState = computed(() =>
+      resolveKnowledgePreviewLayoutState(selectedDocument.value)
+    )
     const previewMode = computed(() =>
       resolveKnowledgePreviewMode(selectedDocument.value, {
         onlyOfficeAvailable: onlyOfficeAvailable.value
       })
     )
-    const shouldUseOnlyOffice = computed(() => previewMode.value === 'onlyoffice')
+    const shouldRenderOnlyOffice = computed(() =>
+      shouldRenderOnlyOfficePreview(selectedDocument.value, {
+        onlyOfficeLoading: onlyOfficeLoading.value,
+        onlyOfficeAvailable: onlyOfficeAvailable.value,
+        onlyOfficeError: onlyOfficeError.value
+      })
+    )
+    const shouldRenderOnlyOfficeHostNode = computed(() =>
+      shouldRenderOnlyOfficeHost(selectedDocument.value, {
+        onlyOfficeLoading: onlyOfficeLoading.value,
+        onlyOfficeAvailable: onlyOfficeAvailable.value,
+        onlyOfficeError: onlyOfficeError.value
+      })
+    )
     const excelPreviewTable = computed(() =>
       selectedDocument.value?.previewKind === 'table'
         ? buildExcelPreviewTable(activePreviewPage.value)
@@ -110,12 +172,16 @@ export default {
       }
     }
 
-    function destroyOnlyOfficeEditor() {
+    function destroyOnlyOfficeEditor() {
-      if (onlyOfficeEditor.value?.destroyEditor) {
+      if (onlyOfficeReadyTimeoutId.value) {
-        onlyOfficeEditor.value.destroyEditor()
+        window.clearTimeout(onlyOfficeReadyTimeoutId.value)
-      }
+        onlyOfficeReadyTimeoutId.value = 0
-      onlyOfficeEditor.value = null
+      }
-    }
+      if (onlyOfficeEditor.value?.destroyEditor) {
+        onlyOfficeEditor.value.destroyEditor()
+      }
+      onlyOfficeEditor.value = null
+    }
 
     async function mountOnlyOfficeEditor(documentId) {
       onlyOfficeLoading.value = true
@@ -126,22 +192,63 @@ export default {
       try {
         const payload = await fetchKnowledgeOnlyOfficeConfig(documentId)
         await loadOnlyOfficeApi(payload.documentServerUrl)
-        await nextTick()
+        await nextTick()
-
+
         if (!window.DocsAPI?.DocEditor) {
           throw new Error('ONLYOFFICE 编辑器未正确加载。')
         }
 
         onlyOfficeHostId.value = `knowledge-onlyoffice-preview-${documentId}`
         await nextTick()
-        onlyOfficeEditor.value = new window.DocsAPI.DocEditor(onlyOfficeHostId.value, payload.config)
+        const config = buildOnlyOfficePreviewConfig(payload.config, {
-        onlyOfficeAvailable.value = true
+          viewportHeight: window.innerHeight
+        })
+        const upstreamEvents = config.events || {}
+        config.events = {
+          ...upstreamEvents,
+          onAppReady(event) {
+            if (onlyOfficeReadyTimeoutId.value) {
+              window.clearTimeout(onlyOfficeReadyTimeoutId.value)
+              onlyOfficeReadyTimeoutId.value = 0
+            }
+            onlyOfficeAvailable.value = true
+            onlyOfficeLoading.value = false
+            upstreamEvents.onAppReady?.(event)
+          },
+          onError(event) {
+            if (onlyOfficeReadyTimeoutId.value) {
+              window.clearTimeout(onlyOfficeReadyTimeoutId.value)
+              onlyOfficeReadyTimeoutId.value = 0
+            }
+            const errorCode = event?.data?.errorCode
+            const errorDescription = event?.data?.errorDescription
+            const message = errorDescription
+              ? `ONLYOFFICE 预览失败：${errorDescription}`
+              : `ONLYOFFICE 预览失败${errorCode ? `（错误码 ${errorCode}）` : '。'}`
+            onlyOfficeError.value = message
+            onlyOfficeLoading.value = false
+            console.error('ONLYOFFICE onError', event)
+            toast(message)
+            upstreamEvents.onError?.(event)
+          }
+        }
+        onlyOfficeEditor.value = new window.DocsAPI.DocEditor(onlyOfficeHostId.value, config)
+        onlyOfficeReadyTimeoutId.value = window.setTimeout(() => {
+          if (!onlyOfficeAvailable.value && !onlyOfficeError.value) {
+            onlyOfficeError.value = 'ONLYOFFICE 预览初始化超时。请检查浏览器是否拦截了 iframe 或混合内容。'
+            onlyOfficeLoading.value = false
+            toast(onlyOfficeError.value)
+          }
+        }, 10000)
         return true
       } catch (error) {
         onlyOfficeError.value = error.message || 'ONLYOFFICE 预览加载失败。'
+        toast(onlyOfficeError.value)
         return false
       } finally {
-        onlyOfficeLoading.value = false
+        if (onlyOfficeError.value) {
+          onlyOfficeLoading.value = false
+        }
       }
     }
 
@@ -158,13 +265,12 @@ export default {
           activeFolder.value = folders.value[0]?.name || ''
         }
 
-        if (options.preserveSelection && selectedDocument.value?.id) {
+        if (options.preserveSelection && selectedDocument.value?.id) {
-          const exists = documents.value.some((doc) => doc.id === selectedDocument.value.id)
+          const exists = documents.value.some((doc) => doc.id === selectedDocument.value.id)
-          if (!exists) {
+          if (!exists) {
-            selectedDocument.value = null
+            closePreview()
-            revokePreviewBlob()
+          }
-          }
+        }
-        }
       } catch (error) {
         emit('summary-change', { totalDocuments: 0 })
         toast(error.message || '知识库加载失败。')
@@ -187,7 +293,9 @@ export default {
         currentPreviewPageIndex.value = 0
 
         if (canUseOnlyOfficePreview(payload)) {
+          previewLoading.value = false
           await mountOnlyOfficeEditor(documentId)
+          return
         }
 
         if (payload.previewKind === 'pdf' || payload.previewKind === 'image') {
@@ -271,13 +379,12 @@ export default {
 
       deletingId.value = document.id
       try {
-        await deleteKnowledgeDocument(document.id)
+        await deleteKnowledgeDocument(document.id)
-        if (selectedDocument.value?.id === document.id) {
+        if (selectedDocument.value?.id === document.id) {
-          selectedDocument.value = null
+          closePreview()
-          revokePreviewBlob()
+        }
-        }
+        await loadLibrary()
-        await loadLibrary()
+        toast('知识库文件已删除。')
-        toast('知识库文件已删除。')
       } catch (error) {
         toast(error.message || '删除失败。')
       } finally {
@@ -291,15 +398,23 @@ export default {
       currentPage.value = 1
     }
 
-    function closePreview() {
+    function closePreview() {
-      selectedDocument.value = null
+      selectedDocument.value = null
-      previewError.value = ''
+      previewLoading.value = false
-      currentPreviewPageIndex.value = 0
+      previewError.value = ''
+      currentPreviewPageIndex.value = 0
       revokePreviewBlob()
       destroyOnlyOfficeEditor()
+      onlyOfficeLoading.value = false
       onlyOfficeError.value = ''
       onlyOfficeAvailable.value = false
     }
+
+    function handleWindowKeydown(event) {
+      if (event.key === 'Escape' && selectedDocument.value) {
+        closePreview()
+      }
+    }
 
     function selectPreviewPage(index) {
       currentPreviewPageIndex.value = index
@@ -314,20 +429,35 @@ export default {
       }
     })
 
-    watch(activeFolder, () => {
+    watch(activeFolder, () => {
-      closePreview()
+      closePreview()
-    })
+    })
-
+
-    onMounted(() => {
+    watch(
-      loadLibrary()
+      () => previewLayoutState.value.isPreviewModalOpen,
-    })
+      async (isPreviewModalOpen) => {
-
+        setBodyScrollLocked(isPreviewModalOpen)
+
+        if (isPreviewModalOpen) {
+          await nextTick()
+          previewDialogPanel.value?.focus?.()
+        }
+      }
+    )
+
+    onMounted(() => {
+      loadLibrary()
+      window.addEventListener('keydown', handleWindowKeydown)
+    })
+
     onBeforeUnmount(() => {
       revokePreviewBlob()
       destroyOnlyOfficeEditor()
+      setBodyScrollLocked(false)
+      window.removeEventListener('keydown', handleWindowKeydown)
     })
-
+
-    return {
+    return {
       activeFolder,
       activePreviewPage,
       changePageSize,
@@ -344,20 +474,23 @@ export default {
       handleFileInput,
       isAdmin,
       loading,
-      pageSize,
+      pageSize,
       pageSizeOpen,
       pageSizes,
       onlyOfficeError,
       onlyOfficeHostId,
       onlyOfficeLoading,
+      previewDialogPanel,
+      previewLayoutState,
       previewMode,
       previewMetaLine,
       previewSecondaryMetaLine,
       previewBlobUrl,
-      previewError,
+      previewError,
-      previewLoading,
+      previewLoading,
-      shouldUseOnlyOffice,
+      shouldRenderOnlyOffice,
-      selectDocument,
+      shouldRenderOnlyOfficeHostNode,
+      selectDocument,
       selectPreviewPage,
       selectedDocument,
       totalCount,

web/src/views/scripts/knowledgePreviewLayout.js

@@ -0,0 +1,6 @@
+export function resolveKnowledgePreviewLayoutState(selectedDocument) {
+  return {
+    isPreviewModalOpen: Boolean(selectedDocument),
+    usesSplitLayout: false
+  }
+}

web/src/views/scripts/knowledgePreviewMode.js

@@ -4,6 +4,30 @@ function supportsOnlyOfficePreview(document) {
   return ONLYOFFICE_EXTENSIONS.has(String(document?.extension || '').toLowerCase())
 }
 
+export function shouldRenderOnlyOfficePreview(document, options = {}) {
+  if (!supportsOnlyOfficePreview(document)) {
+    return false
+  }
+
+  return (
+    Boolean(options.onlyOfficeLoading) ||
+    Boolean(options.onlyOfficeAvailable) ||
+    Boolean(options.onlyOfficeError)
+  )
+}
+
+export function shouldRenderOnlyOfficeHost(document, options = {}) {
+  if (!supportsOnlyOfficePreview(document)) {
+    return false
+  }
+
+  return (
+    Boolean(options.onlyOfficeLoading) ||
+    Boolean(options.onlyOfficeAvailable) ||
+    Boolean(options.onlyOfficeError)
+  )
+}
+
 export function resolveKnowledgePreviewMode(document, options = {}) {
   if (!document) {
     return 'none'

web/src/views/scripts/onlyOfficePreviewConfig.js

@@ -0,0 +1,30 @@
+function clampHeight(viewportHeight) {
+  const numericHeight = Number(viewportHeight)
+  if (!Number.isFinite(numericHeight) || numericHeight <= 0) {
+    return 720
+  }
+
+  return Math.max(520, numericHeight - 220)
+}
+
+export function buildOnlyOfficePreviewConfig(config, options = {}) {
+  const viewportHeight = options.viewportHeight
+  const editorConfig = {
+    ...(config.editorConfig || {}),
+    embedded: {
+      embedUrl: '',
+      fullscreenUrl: '',
+      saveUrl: '',
+      shareUrl: '',
+      toolbarDocked: 'top'
+    }
+  }
+
+  return {
+    ...config,
+    type: 'embedded',
+    editorConfig,
+    width: '100%',
+    height: `${clampHeight(viewportHeight)}px`
+  }
+}

web/tests/knowledge-preview-layout.test.mjs

@@ -0,0 +1,25 @@
+import assert from 'node:assert/strict'
+
+import { resolveKnowledgePreviewLayoutState } from '../src/views/scripts/knowledgePreviewLayout.js'
+
+function testUsesLibraryOnlyLayoutWithoutSelection() {
+  assert.deepEqual(resolveKnowledgePreviewLayoutState(null), {
+    isPreviewModalOpen: false,
+    usesSplitLayout: false
+  })
+}
+
+function testUsesModalPreviewLayoutWhenDocumentIsSelected() {
+  assert.deepEqual(resolveKnowledgePreviewLayoutState({ id: 'doc-1' }), {
+    isPreviewModalOpen: true,
+    usesSplitLayout: false
+  })
+}
+
+function run() {
+  testUsesLibraryOnlyLayoutWithoutSelection()
+  testUsesModalPreviewLayoutWhenDocumentIsSelected()
+  console.log('knowledge preview layout tests passed')
+}
+
+run()

web/tests/knowledge-preview-mode.test.mjs

@@ -1,6 +1,10 @@
 import assert from 'node:assert/strict'
 
-import { resolveKnowledgePreviewMode } from '../src/views/scripts/knowledgePreviewMode.js'
+import {
+  resolveKnowledgePreviewMode,
+  shouldRenderOnlyOfficeHost,
+  shouldRenderOnlyOfficePreview
+} from '../src/views/scripts/knowledgePreviewMode.js'
 
 function testPrefersOnlyOfficeForSupportedOfficeFileWhenAvailable() {
   const document = {
@@ -29,10 +33,108 @@ function testUsesPreviewKindForNonOnlyOfficeFile() {
   assert.equal(resolveKnowledgePreviewMode(document, { onlyOfficeAvailable: false }), 'pdf')
 }
 
+function testRendersOnlyOfficeContainerWhileOfficePreviewIsLoading() {
+  const document = {
+    extension: 'docx',
+    previewKind: 'text'
+  }
+
+  assert.equal(
+    shouldRenderOnlyOfficePreview(document, {
+      onlyOfficeLoading: true,
+      onlyOfficeAvailable: false
+    }),
+    true
+  )
+}
+
+function testKeepsOnlyOfficeContainerVisibleWhenOfficePreviewHasError() {
+  const document = {
+    extension: 'docx',
+    previewKind: 'text'
+  }
+
+  assert.equal(
+    shouldRenderOnlyOfficePreview(document, {
+      onlyOfficeLoading: false,
+      onlyOfficeAvailable: false,
+      onlyOfficeError: 'timeout'
+    }),
+    true
+  )
+}
+
+function testDoesNotRenderOnlyOfficeContainerAfterFailedMount() {
+  const document = {
+    extension: 'xlsx',
+    previewKind: 'table'
+  }
+
+  assert.equal(
+    shouldRenderOnlyOfficePreview(document, {
+      onlyOfficeLoading: false,
+      onlyOfficeAvailable: false
+    }),
+    false
+  )
+}
+
+function testRendersOnlyOfficeHostWhileOfficePreviewIsLoading() {
+  const document = {
+    extension: 'pptx',
+    previewKind: 'slides'
+  }
+
+  assert.equal(
+    shouldRenderOnlyOfficeHost(document, {
+      onlyOfficeLoading: true,
+      onlyOfficeAvailable: false
+    }),
+    true
+  )
+}
+
+function testKeepsOnlyOfficeHostVisibleWhenOfficePreviewHasError() {
+  const document = {
+    extension: 'xlsx',
+    previewKind: 'table'
+  }
+
+  assert.equal(
+    shouldRenderOnlyOfficeHost(document, {
+      onlyOfficeLoading: false,
+      onlyOfficeAvailable: false,
+      onlyOfficeError: 'timeout'
+    }),
+    true
+  )
+}
+
+function testDoesNotRenderOnlyOfficeHostForNonOfficeDocuments() {
+  const document = {
+    extension: 'pdf',
+    previewKind: 'pdf'
+  }
+
+  assert.equal(
+    shouldRenderOnlyOfficeHost(document, {
+      onlyOfficeLoading: true,
+      onlyOfficeAvailable: false
+    }),
+    false
+  )
+}
+
 function run() {
   testPrefersOnlyOfficeForSupportedOfficeFileWhenAvailable()
   testFallsBackToStructuredPreviewForOfficeFileWhenOnlyOfficeUnavailable()
   testUsesPreviewKindForNonOnlyOfficeFile()
+  testRendersOnlyOfficeContainerWhileOfficePreviewIsLoading()
+  testKeepsOnlyOfficeContainerVisibleWhenOfficePreviewHasError()
+  testDoesNotRenderOnlyOfficeContainerAfterFailedMount()
+  testRendersOnlyOfficeHostWhileOfficePreviewIsLoading()
+  testKeepsOnlyOfficeHostVisibleWhenOfficePreviewHasError()
+  testDoesNotRenderOnlyOfficeHostForNonOfficeDocuments()
   console.log('knowledge preview mode tests passed')
 }
 

web/tests/onlyoffice-preview-config.test.mjs

@@ -0,0 +1,54 @@
+import assert from 'node:assert/strict'
+
+import { buildOnlyOfficePreviewConfig } from '../src/views/scripts/onlyOfficePreviewConfig.js'
+
+function testUsesExplicitPixelHeightFromViewport() {
+  const config = buildOnlyOfficePreviewConfig({ width: '50%', height: '100%' }, { viewportHeight: 900 })
+
+  assert.equal(config.width, '100%')
+  assert.equal(config.height, '680px')
+}
+
+function testFallsBackToSafeDefaultHeight() {
+  const config = buildOnlyOfficePreviewConfig({}, {})
+
+  assert.equal(config.height, '720px')
+}
+
+function testClampsSmallViewportHeight() {
+  const config = buildOnlyOfficePreviewConfig({}, { viewportHeight: 600 })
+
+  assert.equal(config.height, '520px')
+}
+
+function testUsesEmbeddedPreviewModeWithMinimalToolbar() {
+  const config = buildOnlyOfficePreviewConfig(
+    {
+      editorConfig: {
+        customization: {
+          compactHeader: true
+        }
+      }
+    },
+    {}
+  )
+
+  assert.equal(config.type, 'embedded')
+  assert.deepEqual(config.editorConfig.embedded, {
+    embedUrl: '',
+    fullscreenUrl: '',
+    saveUrl: '',
+    shareUrl: '',
+    toolbarDocked: 'top'
+  })
+}
+
+function run() {
+  testUsesExplicitPixelHeightFromViewport()
+  testFallsBackToSafeDefaultHeight()
+  testClampsSmallViewportHeight()
+  testUsesEmbeddedPreviewModeWithMinimalToolbar()
+  console.log('onlyoffice preview config tests passed')
+}
+
+run()