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

2026-05-09 07:29:49 +00:00
parent d9133193e8
commit 94122fd34b
26 changed files with 20232 additions and 300 deletions
--- a/.env
+++ b/.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"]'
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -6,14 +6,15 @@ services:
    depends_on:
      onlyoffice:
        condition: service_started
-    environment:
-      WEB_HOST: 0.0.0.0
-      SERVER_HOST: 0.0.0.0
-      SERVER_VENV_DIR: /tmp/x-financial-server-venv
-      ONLYOFFICE_ENABLED: "${ONLYOFFICE_ENABLED:-true}"
-      ONLYOFFICE_PUBLIC_URL: "${ONLYOFFICE_PUBLIC_URL:-http://127.0.0.1:${ONLYOFFICE_PORT:-8082}}"
-      ONLYOFFICE_BACKEND_URL: "${ONLYOFFICE_BACKEND_URL:-http://main:${SERVER_PORT:-8000}}"
-      ONLYOFFICE_JWT_SECRET: "${ONLYOFFICE_JWT_SECRET:-x-financial-onlyoffice-dev-secret}"
+    environment:
+      WEB_HOST: 0.0.0.0
+      SERVER_HOST: 0.0.0.0
+      SERVER_VENV_DIR: /tmp/x-financial-server-venv
+      X_FINANCIAL_PREFER_ENV_FILE: "true"
+      ONLYOFFICE_ENABLED: "${ONLYOFFICE_ENABLED:-true}"
+      ONLYOFFICE_PUBLIC_URL: "${ONLYOFFICE_PUBLIC_URL:-http://127.0.0.1:${ONLYOFFICE_PORT:-8082}}"
+      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:
-      test: ["CMD-SHELL", "curl -fsS http://127.0.0.1:${WEB_PORT:-5173}/ >/dev/null || exit 1"]
-      interval: 15s
-      timeout: 5s
-      retries: 10
-      start_period: 180s
-
-  onlyoffice:
-    image: onlyoffice/documentserver:latest
-    container_name: x-financial-onlyoffice
+    healthcheck:
+      test: ["CMD-SHELL", "curl -fsS http://127.0.0.1:${WEB_PORT:-5173}/ >/dev/null || exit 1"]
+      interval: 15s
+      timeout: 5s
+      retries: 10
+      start_period: 180s
+    networks:
+      - financial-internal
+
+  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:
-      test: ["CMD-SHELL", "curl -fsS http://127.0.0.1/healthcheck >/dev/null || exit 1"]
-      interval: 15s
-      timeout: 5s
-      retries: 10
-      start_period: 60s
+    healthcheck:
+      test: ["CMD-SHELL", "curl -fsS http://127.0.0.1/healthcheck >/dev/null || exit 1"]
+      interval: 15s
+      timeout: 5s
+      retries: 10
+      start_period: 60s
+    networks:
+      - financial-internal
+
+networks:
+  financial-internal:
+    name: financial-internal
--- a/1
+++ b/1
@@ -0,0 +1 @@
+/usr/bin/bash: line 1: rg: command not found
--- a/server/server_start.sh
+++ b/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
--- a/server/src/app/core/config.py
+++ b/server/src/app/core/config.py
@@ -1,22 +1,32 @@
-from __future__ import annotations
-
-from functools import lru_cache
-from os import environ
-from pathlib import Path
-
-from pydantic import Field
-from pydantic_settings import BaseSettings, SettingsConfigDict
-
-SERVER_DIR = Path(__file__).resolve().parents[3]
-ROOT_DIR = SERVER_DIR.parent
+from __future__ import annotations
+
+from os import environ
+from pathlib import Path
+
+from dotenv import dotenv_values
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+SERVER_DIR = Path(__file__).resolve().parents[3]
+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):
-    model_config = SettingsConfigDict(
-        env_file=(ROOT_DIR / ".env", SERVER_DIR / ".env"),
-        env_file_encoding="utf-8",
-        extra="ignore",
-    )
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_file=DEFAULT_ENV_FILES,
+        env_file_encoding="utf-8",
+        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()
-
-
-@lru_cache
-def get_settings() -> Settings:
-    return Settings()
-
-
-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()
+
+def _resolve_env_files() -> tuple[Path, ...]:
+    env_files = Settings.model_config.get("env_file") or ()
+    return tuple(Path(item) for item in env_files)
+
+
+def _build_settings_signature() -> tuple[tuple[str, bool, int | None, int | None], ...]:
+    signature: list[tuple[str, bool, int | None, int | None]] = []
+
+    for env_file in _resolve_env_files():
+        if not env_file.exists():
+            signature.append((str(env_file), False, None, None))
+            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()
--- a/server/src/app/services/knowledge.py
+++ b/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(
-        self,
-        document_id: str,
-        current_user: CurrentUserContext,
-    ) -> KnowledgeOnlyOfficeConfigRead:
-        self.ensure_library_ready()
-        settings = get_settings()
-        if not settings.onlyoffice_enabled:
-            raise ValueError("ONLYOFFICE 预览未启用。")
-        if not settings.onlyoffice_public_url or not settings.onlyoffice_backend_url:
-            raise ValueError("ONLYOFFICE 地址配置不完整。")
-        if not settings.onlyoffice_jwt_secret:
-            raise ValueError("ONLYOFFICE JWT 密钥未配置。")
+    def build_onlyoffice_config(
+        self,
+        document_id: str,
+        current_user: CurrentUserContext,
+    ) -> KnowledgeOnlyOfficeConfigRead:
+        self.ensure_library_ready()
+        settings = get_settings()
+        if not settings.onlyoffice_enabled:
+            logger.warning(
+                "ONLYOFFICE disabled in runtime config 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_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)
-
-        config: dict[str, Any] = {
-            "documentType": document_type,
-            "document": {
+        document_key = self._build_onlyoffice_document_key(entry)
+
+        config: dict[str, Any] = {
+            "documentType": document_type,
+            "document": {
                "fileType": extension,
                "key": document_key,
-                "title": entry["original_name"],
-                "url": document_url,
-                "permissions": {
-                    "download": True,
-                    "edit": can_edit,
-                    "print": True,
-                    "copy": True,
+                "title": entry["original_name"],
+                "url": document_url,
+                "permissions": {
+                    "download": True,
+                    "edit": False,
+                    "print": True,
+                    "copy": True,
+                },
+            },
+            "editorConfig": {
+                "mode": "view",
+                "lang": "zh-CN",
+                "callbackUrl": callback_url,
+                "user": {
+                    "id": current_user.username,
+                    "name": current_user.name,
                },
-            },
-            "editorConfig": {
-                "mode": "edit" if can_edit else "view",
-                "lang": "zh-CN",
-                "callbackUrl": callback_url,
-                "user": {
-                    "id": current_user.username,
-                    "name": current_user.name,
-                },
-                "customization": {
-                    "compactHeader": True,
-                    "compactToolbar": True,
-                    "toolbarNoTabs": False,
-                    "autosave": can_edit,
-                    "forcesave": can_edit,
-                },
-            },
-            "width": "100%",
-            "height": "100%",
-        }
+                "customization": {
+                    "compactHeader": True,
+                    "compactToolbar": True,
+                    "toolbarNoTabs": False,
+                    "autosave": False,
+                    "forcesave": False,
+                },
+            },
+            "width": "100%",
+            "height": "100%",
+        }
        config["token"] = jwt.encode(config, settings.onlyoffice_jwt_secret, algorithm="HS256")

        return KnowledgeOnlyOfficeConfigRead(
--- a/server/src/x_financial_server.egg-info/PKG-INFO
+++ b/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
--- a/server/src/x_financial_server.egg-info/SOURCES.txt
+++ b/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
--- a/server/src/x_financial_server.egg-info/requires.txt
+++ b/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
--- a/server/storage/knowledge/.index.json
+++ b/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
    }
  ]
 }
--- a/server/storage/knowledge/财务知识库/6cad2936d57242d29d26f6fbb6314767__2508.19855v3.pdf
+++ b/server/storage/knowledge/财务知识库/6cad2936d57242d29d26f6fbb6314767__2508.19855v3.pdf
--- a/server/storage/knowledge/财务知识库/8af9350f0e02488aaf0df2001286b764__差旅费季度报销258878.xlsx
+++ b/server/storage/knowledge/财务知识库/8af9350f0e02488aaf0df2001286b764__差旅费季度报销258878.xlsx
--- a/server/storage/knowledge/财务知识库/b01fe587d3d941f0a25d500751b27094__面向财务领域的大语言模型
+++ b/server/storage/knowledge/财务知识库/b01fe587d3d941f0a25d500751b27094__面向财务领域的大语言模型
--- a/server/tests/test_config_settings_reload.py
+++ b/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()
--- a/server/tests/test_env_file_precedence.py
+++ b/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
--- a/server/tests/test_knowledge_onlyoffice_config.py
+++ b/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()
--- a/start.sh
+++ b/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
--- a/web/src/assets/styles/views/policies-view.css
+++ b/web/src/assets/styles/views/policies-view.css
@@ -5,22 +5,20 @@
  animation: fadeUp 220ms var(--ease) both;
 }

-.knowledge-grid {
-  height: 100%;
-  min-height: 0;
-  display: grid;
-  grid-template-columns: minmax(0, 1fr) 0;
-  gap: 0;
-  transition: grid-template-columns 320ms var(--ease), gap 320ms var(--ease);
-}
-
-.knowledge-grid.has-preview {
-  grid-template-columns: minmax(560px, 1fr) minmax(420px, 0.82fr);
-  gap: 16px;
-}
-
-.knowledge-main,
-.preview-column {
+.knowledge-grid {
+  height: 100%;
+  min-height: 0;
+  display: grid;
+  grid-template-columns: minmax(0, 1fr);
+  gap: 0;
+}
+
+.knowledge-grid.has-preview {
+  grid-template-columns: minmax(0, 1fr);
+}
+
+.knowledge-main,
+.preview-column {
  min-width: 0;
  min-height: 0;
 }
@@ -470,17 +468,11 @@ th {
  color: #fff;
 }

-.preview-column {
-  min-width: 0;
-  min-height: 0;
-  overflow: hidden;
-}
-
-.preview-panel {
-  height: 100%;
-  min-height: 0;
-  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 {
-  min-height: 0;
-  margin-top: 18px;
-}
-
-.preview-status {
-  display: grid;
+.preview-viewer {
+  min-height: 0;
+  margin-top: 18px;
+  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-image-wrap {
-  min-height: 0;
-  overflow: hidden;
-  border: 1px solid #edf2f7;
-  border-radius: 12px;
-  background: #fff;
+.preview-embed-wrap,
+.preview-image-wrap {
+  min-height: 0;
+  height: 100%;
+  overflow: hidden;
+  border: 1px solid #edf2f7;
+  border-radius: 12px;
+  background: #fff;
 }

-.preview-embed {
-  width: 100%;
-  height: 100%;
-  min-height: 560px;
-  border: 0;
-}
+.preview-embed {
+  width: 100%;
+  height: 100%;
+  min-height: 0;
+  border: 0;
+}

 .preview-image-wrap {
  display: grid;
@@ -608,25 +634,38 @@ th {
  object-fit: contain;
 }

-.onlyoffice-preview-wrap {
-  min-height: 0;
-  overflow: hidden;
-  border: 1px solid #dbe4ee;
-  border-radius: 12px;
-  background: #fff;
-}
+.onlyoffice-preview-wrap {
+  position: relative;
+  min-height: 0;
+  height: 100%;
+  overflow: hidden;
+  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 {
-  width: 100%;
-  min-height: 720px;
-}
-
-.excel-preview-wrap {
-  min-height: 0;
-  overflow: hidden;
-  border: 1px solid #dbe4ee;
-  border-radius: 12px;
-  background: #fff;
+.excel-preview-wrap {
+  min-height: 0;
+  height: 100%;
+  overflow: hidden;
+  border: 1px solid #dbe4ee;
+  border-radius: 12px;
+  background: #fff;
 }

 .excel-sheet-tabs {
@@ -707,13 +746,18 @@ th {
  border-bottom: 0;
 }

-.page-stage {
-  min-height: 0;
-  overflow: auto;
-  display: grid;
-  gap: 20px;
-  padding-right: 6px;
-}
+.page-stage {
+  min-height: 0;
+  height: 100%;
+  overflow: auto;
+  display: grid;
+  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-panel-leave-active {
-  transition: opacity 240ms ease, transform 320ms var(--ease);
-}
-
-.preview-panel-enter-from,
-.preview-panel-leave-to {
-  opacity: 0;
-  transform: translateX(24px) scale(0.98);
-}
+.preview-modal-enter-active,
+.preview-modal-leave-active {
+  transition: opacity 220ms ease;
+}
+
+.preview-modal-enter-active .preview-modal-shell,
+.preview-modal-leave-active .preview-modal-shell {
+  transition: transform 320ms var(--ease), opacity 220ms ease;
+}
+
+.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) {
-  .knowledge-grid.has-preview {
-    grid-template-columns: minmax(0, 1fr) minmax(360px, 0.78fr);
-  }
-}
-
-@media (max-width: 1080px) {
-  .knowledge-grid,
-  .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) {
-  .panel-title,
-  .preview-head,
+@media (max-width: 760px) {
+  .panel-title,
+  .preview-head,
  .viewer-toolbar {
    flex-direction: column;
    align-items: stretch;
@@ -872,9 +920,31 @@ th {
    justify-items: stretch;
  }

-  .pager,
-  .page-size-wrap,
-  .page-size {
-    justify-self: stretch;
-  }
-}
+  .pager,
+  .page-size-wrap,
+  .page-size {
+    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;
+  }
+}
--- a/web/src/views/PoliciesView.vue
+++ b/web/src/views/PoliciesView.vue
@@ -1,15 +1,15 @@
 <template>
-  <section class="knowledge-page">
-    <div class="knowledge-grid" :class="{ 'has-preview': selectedDocument }">
-      <section class="knowledge-main">
-        <article class="library-panel panel">
-          <header class="panel-title">
-            <div>
-              <h2>文档库 / 文件夹</h2>
-              <p>默认展示文件列表，点击具体文件后可在右侧展开预览。</p>
-            </div>
-            <label class="file-search">
-              <i class="mdi mdi-magnify"></i>
+  <section class="knowledge-page">
+    <div class="knowledge-grid" :class="{ 'has-preview': previewLayoutState.usesSplitLayout }">
+      <section class="knowledge-main">
+        <article class="library-panel panel">
+          <header class="panel-title">
+            <div>
+              <h2>文档库 / 文件夹</h2>
+              <p>默认展示文件列表，点击具体文件后以弹窗方式展开预览。</p>
+            </div>
+            <label class="file-search">
+              <i class="mdi mdi-magnify"></i>
              <input v-model="documentSearch" type="search" placeholder="搜索当前文件夹内文件" />
            </label>
          </header>
@@ -159,18 +159,29 @@
              </footer>
            </section>
          </div>
-        </article>
-      </section>
-
-      <Transition name="preview-panel">
-        <aside v-if="selectedDocument" class="preview-column">
-          <article class="preview-panel panel">
-            <header class="preview-head">
-              <div class="preview-copy">
-                <h2>{{ selectedDocument.name }}</h2>
-                <p class="preview-summary-line">
-                  <span v-for="part in previewMetaLine" :key="part">{{ part }}</span>
-                </p>
+        </article>
+      </section>
+      <Teleport to="body">
+        <Transition name="preview-modal">
+          <div
+            v-if="previewLayoutState.isPreviewModalOpen"
+            class="preview-modal-overlay"
+            role="presentation"
+            @click.self="closePreview"
+          >
+            <aside class="preview-modal-shell" role="dialog" aria-modal="true" aria-labelledby="knowledge-preview-title">
+              <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>
-
-            <div class="preview-viewer">
-              <div v-if="previewLoading" class="preview-status">正在加载预览...</div>
-              <div v-else-if="previewError" class="preview-status error">{{ previewError }}</div>
+            </header>
+
+            <div class="preview-viewer">
+              <div v-if="shouldRenderOnlyOffice" class="onlyoffice-preview-wrap">
+                <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>
-          </article>
-        </aside>
-      </Transition>
-    </div>
-  </section>
-</template>
+                </div>
+              </div>
+            </div>
+              </article>
+            </aside>
+          </div>
+        </Transition>
+      </Teleport>
+    </div>
+  </section>
+</template>

 <script src="./scripts/PoliciesView.js"></script>

--- a/web/src/views/scripts/PoliciesView.js
+++ b/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(() =>
-      buildPreviewSecondaryMetaLine(selectedDocument.value, activePreviewPage.value)
-    )
+    const previewSecondaryMetaLine = computed(() =>
+      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() {
-      if (onlyOfficeEditor.value?.destroyEditor) {
-        onlyOfficeEditor.value.destroyEditor()
-      }
-      onlyOfficeEditor.value = null
-    }
+    function destroyOnlyOfficeEditor() {
+      if (onlyOfficeReadyTimeoutId.value) {
+        window.clearTimeout(onlyOfficeReadyTimeoutId.value)
+        onlyOfficeReadyTimeoutId.value = 0
+      }
+      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)
-        onlyOfficeAvailable.value = true
+        const config = buildOnlyOfficePreviewConfig(payload.config, {
+          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) {
-          const exists = documents.value.some((doc) => doc.id === selectedDocument.value.id)
-          if (!exists) {
-            selectedDocument.value = null
-            revokePreviewBlob()
-          }
-        }
+        if (options.preserveSelection && selectedDocument.value?.id) {
+          const exists = documents.value.some((doc) => doc.id === selectedDocument.value.id)
+          if (!exists) {
+            closePreview()
+          }
+        }
      } 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)
-        if (selectedDocument.value?.id === document.id) {
-          selectedDocument.value = null
-          revokePreviewBlob()
-        }
-        await loadLibrary()
-        toast('知识库文件已删除。')
+        await deleteKnowledgeDocument(document.id)
+        if (selectedDocument.value?.id === document.id) {
+          closePreview()
+        }
+        await loadLibrary()
+        toast('知识库文件已删除。')
      } catch (error) {
        toast(error.message || '删除失败。')
      } finally {
@@ -291,15 +398,23 @@ export default {
      currentPage.value = 1
    }

-    function closePreview() {
-      selectedDocument.value = null
-      previewError.value = ''
-      currentPreviewPageIndex.value = 0
+    function closePreview() {
+      selectedDocument.value = null
+      previewLoading.value = false
+      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, () => {
-      closePreview()
-    })
-
-    onMounted(() => {
-      loadLibrary()
-    })
-
+    watch(activeFolder, () => {
+      closePreview()
+    })
+
+    watch(
+      () => 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,
-      previewLoading,
-      shouldUseOnlyOffice,
-      selectDocument,
+      previewError,
+      previewLoading,
+      shouldRenderOnlyOffice,
+      shouldRenderOnlyOfficeHostNode,
+      selectDocument,
      selectPreviewPage,
      selectedDocument,
      totalCount,
--- a/web/src/views/scripts/knowledgePreviewLayout.js
+++ b/web/src/views/scripts/knowledgePreviewLayout.js
@@ -0,0 +1,6 @@
+export function resolveKnowledgePreviewLayoutState(selectedDocument) {
+  return {
+    isPreviewModalOpen: Boolean(selectedDocument),
+    usesSplitLayout: false
+  }
+}
--- a/web/src/views/scripts/knowledgePreviewMode.js
+++ b/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'
--- a/web/src/views/scripts/onlyOfficePreviewConfig.js
+++ b/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`
+  }
+}
--- a/web/tests/knowledge-preview-layout.test.mjs
+++ b/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()
--- a/web/tests/knowledge-preview-mode.test.mjs
+++ b/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')
 }

--- a/web/tests/onlyoffice-preview-config.test.mjs
+++ b/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()
				`@@ -0,0 +1 @@`
				`/usr/bin/bash: line 1: rg: command not found`