chore: 导入旧记忆备份供恢复

projects/d1932ed6-07d3-4463-a224-8534ffd69a07/curated/development/Common Issues & Troubleshooting Guide.md

@@ -0,0 +1,109 @@
+---
+title: Common Issues & Troubleshooting Guide
+type: curated
+permalink: main/projects/d1932ed6-07d3-4463-a224-8534ffd69a07/curated/development/common-issues-troubleshooting-guide
+stable_id: 0f32d409-b512-4fc9-b65e-59d8a70359b8
+scope: project
+project_id: d1932ed6-07d3-4463-a224-8534ffd69a07
+workspace_type: development
+usage_profile_id: null
+preference_context: development
+document_type: troubleshooting
+revision: 1
+source_memory_ids: []
+source_checkpoint_ids: []
+source_file_ids: []
+source_git_commit: 346195c0699cb8a1dbf5a9576daad945003e5d10
+source_git_commits:
+- 346195c0699cb8a1dbf5a9576daad945003e5d10
+source_agent_sync_ids: []
+model_connection: Sub2API
+model_name: openai/gpt-oss-120b
+source_count: 25
+source_revisions: {}
+source_dispositions:
+  processed: 25
+  unchanged: 0
+  unsupported: 0
+  skipped: 0
+cited_source_ids:
+- global_guidance_document:8a861a5f-35c3-4f95-bd5b-6b2297888f56
+- global_guidance_document:e4fc35f2-1606-4b79-9c1e-367edeea97d0
+job_cited_source_ids:
+- global_guidance_document:8a861a5f-35c3-4f95-bd5b-6b2297888f56
+- global_guidance_document:e4fc35f2-1606-4b79-9c1e-367edeea97d0
+conflicts: []
+supersedes: []
+preferences:
+- statement: AI 驱动的记忆同步与 Git 集成默认关闭
+  level: workspace
+  workspace_types:
+  - development
+  workspace_ids:
+  - d1932ed6-07d3-4463-a224-8534ffd69a07
+  source_ids:
+  - global_guidance_memory:3f91189b-11a1-45bb-8357-4f413dc1609d
+  counterexample_source_ids: []
+  occurrence_count: 1
+  explicit: true
+  confidence: 1.0
+  status: current
+- statement: 日常交流使用中文（包括文档、代码注释等）
+  level: workspace
+  workspace_types:
+  - development
+  workspace_ids:
+  - d1932ed6-07d3-4463-a224-8534ffd69a07
+  source_ids:
+  - global_guidance_memory:7429c22e-50ff-458a-97c0-423c679904c7
+  counterexample_source_ids: []
+  occurrence_count: 1
+  explicit: true
+  confidence: 1.0
+  status: current
+source_cursor: 292
+source_hash: deb30a6b83a03f25e5a91c6b2d68024ae3de216638efb5597267ac9555bb804f
+prompt_version: 2026-08-12.3
+schema_version: '3'
+curation_job_id: ef181130-6e65-470d-be87-1c06a2de345c
+created_at: '2026-09-02T18:36:51.454085+00:00'
+updated_at: '2026-09-02T18:36:51.454519+00:00'
+tags:
+- troubleshooting
+- development
+---
+
+# 常见问题及排障指南 (Troubleshooting)
+
+## 1. Docker 执行超时 (3 秒断连)
+- **症状**：`docker exec` 长时间运行的命令在约 3 秒后被强制中止。  
+- **根因**：Docker‑Py 默认为 hijacked socket 设置了 3 秒的全局 timeout。  
+- **解决方案**：在脚本（如 `deploy.py`）中获取裸 socket 后调用 `socket.settimeout(None)`，或在 `docker-py` 调用前使用 `docker.from_env(timeout=None)`。  
+- **参考**：`global_guidance_document:8a861a5f-35c3-4f95-bd5b-6b2297888f56` 中的说明。
+
+## 2. Docker Hub 代理配置失效
+- **症状**：`docker pull` 失败，提示无法连接到镜像仓库。  
+- **根因**：Docker Desktop 代理模式未设为 *Manual*，或地址填写错误。  
+- **解决方案**：打开 Docker Desktop → Settings → Resources → Proxies，勾选 *Manual*，填写 `http://127.0.0.1:7897` 作为 HTTP 与 HTTPS 代理。保存后重启 Docker 并验证 `docker pull hello-world` 正常。  
+- **参考**：同上经验文档。
+
+## 3. PowerShell 发送 JSON 失真
+- **症状**：使用 `Invoke‑WebRequest` 发送 JSON 时，双引号被吞掉导致请求体错误。  
+- **根因**：PowerShell 对直接传入字符串的引号做了转义。  
+- **解决方案**：先将 JSON 写入临时文件，再使用 `--data-binary @file` 方式上传。  
+- **参考**：`global_guidance_document:8a861a5f-35c3-4f95-bd5b-6b2297888f56` 中的技巧。
+
+## 4. FastAPI 异步函数中阻塞 I/O
+- **症状**：FastAPI 路由挂起，CPU 使用率飙升，接口响应迟缓。  
+- **根因**：在 `async def` 中直接调用阻塞库（如 `pymysql`, `requests`, 文件读写）。  
+- **解决方案**：改为普通 `def`，FastAPI 会自动将其放入线程池，或使用 `run_in_executor` 包装。  
+- **参考**：`global_guidance_document:8a861a5f-35c3-4f95-bd5b-6b2297888f56`。
+
+## 5. Vaultwarden 凭证查找不匹配
+- **症状**：在登录或 API 调用前未能自动获取密码，系统提示手动输入。  
+- **根因**：Vaultwarden 中存在多条匹配项或根本无匹配。  
+- **解决方案**：确保每条凭证的 “名称” 唯一；在脚本中使用 `search_one`（唯一匹配）而非列表返回；如果需要手动选择，请提示用户并验证选择。  
+- **参考**：`global_guidance_memory:105b328f-4bda-4641-90a7-7282ef156316`。
+
+---
+**参考来源**: `global_guidance_document:8a861a5f-35c3-4f95-bd5b-6b2297888f56`, `global_guidance_document:e4fc35f2-1606-4b79-9c1e-367edeea97d0`

projects/d1932ed6-07d3-4463-a224-8534ffd69a07/curated/development/NextOffice 维护与运维手册.md

@@ -0,0 +1,144 @@
+---
+title: NextOffice 维护与运维手册
+type: curated
+permalink: main/projects/d1932ed6-07d3-4463-a224-8534ffd69a07/curated/development/next-office-维护与运维手册
+stable_id: 162cba10-fa5f-43d4-8382-48bee155f500
+scope: project
+project_id: d1932ed6-07d3-4463-a224-8534ffd69a07
+workspace_type: development
+usage_profile_id: null
+preference_context: development
+document_type: maintenance
+revision: 1
+source_memory_ids: []
+source_checkpoint_ids: []
+source_file_ids: []
+source_git_commit: 346195c0699cb8a1dbf5a9576daad945003e5d10
+source_git_commits:
+- 346195c0699cb8a1dbf5a9576daad945003e5d10
+source_agent_sync_ids: []
+model_connection: Sub2API
+model_name: openai/gpt-oss-120b
+source_count: 25
+source_revisions: {}
+source_dispositions:
+  processed: 25
+  unchanged: 0
+  unsupported: 0
+  skipped: 0
+cited_source_ids:
+- git:manage.py
+- git:requirements.txt
+- global_guidance_memory:bf88c265-4749-4c50-85bc-4bae25298cd5
+- global_guidance_memory:5ed86f53-b53e-4534-8e51-d3a010069d5e
+- global_guidance_memory:105b328f-4bda-4641-90a7-7282ef156316
+- global_guidance_document:e4fc35f2-1606-4b79-9c1e-367edeea97d0
+- global_guidance_document:2b47472d-3ac2-4394-8646-c6bf1c0fc270
+- global_guidance_memory:ff34c6eb-6bba-41e5-9e43-ff80941fa823
+job_cited_source_ids:
+- git:manage.py
+- git:requirements.txt
+- global_guidance_memory:bf88c265-4749-4c50-85bc-4bae25298cd5
+- global_guidance_memory:5ed86f53-b53e-4534-8e51-d3a010069d5e
+- global_guidance_memory:105b328f-4bda-4641-90a7-7282ef156316
+- global_guidance_document:e4fc35f2-1606-4b79-9c1e-367edeea97d0
+- global_guidance_document:2b47472d-3ac2-4394-8646-c6bf1c0fc270
+- global_guidance_memory:ff34c6eb-6bba-41e5-9e43-ff80941fa823
+conflicts: []
+supersedes: []
+preferences:
+- statement: 在任何登录、SSH、数据库或 API 调用前先搜索 Vaultwarden，唯一匹配则直接使用
+  level: scenario
+  workspace_types:
+  - development
+  workspace_ids: []
+  source_ids:
+  - global_guidance_memory:105b328f-4bda-4641-90a7-7282ef156316
+  counterexample_source_ids: []
+  occurrence_count: 1
+  explicit: true
+  confidence: 1.0
+  status: current
+- statement: 项目记忆使用 `aidocs/project_context.md`，文件位于 `.gitignore`，提交时仅提交代码变更
+  level: scenario
+  workspace_types:
+  - development
+  workspace_ids: []
+  source_ids:
+  - global_guidance_memory:5ed86f53-b53e-4534-8e51-d3a010069d5e
+  counterexample_source_ids: []
+  occurrence_count: 1
+  explicit: true
+  confidence: 1.0
+  status: current
+- statement: 使用最简且正确的实现（KISS & YAGNI）
+  level: scenario
+  workspace_types:
+  - development
+  workspace_ids: []
+  source_ids:
+  - global_guidance_memory:bf88c265-4749-4c50-85bc-4bae25298cd5
+  counterexample_source_ids: []
+  occurrence_count: 1
+  explicit: true
+  confidence: 1.0
+  status: current
+source_cursor: 292
+source_hash: deb30a6b83a03f25e5a91c6b2d68024ae3de216638efb5597267ac9555bb804f
+prompt_version: 2026-08-12.3
+schema_version: '3'
+curation_job_id: ef181130-6e65-470d-be87-1c06a2de345c
+created_at: '2026-09-02T18:36:56.356802+00:00'
+updated_at: '2026-09-02T18:36:56.357394+00:00'
+tags:
+- maintenance
+- development
+- NextOffice
+---
+
+# NextOffice 维护与运维手册
+
+## 目标与范围
+本手册面向已成功部署的 NextOffice 环境，提供日常运维、备份、日志检查、配置变更等操作指南。遵循全局 **KISS & YAGNI**、**复用已有框架** 与 **凭证统一管理** 的原则。
+
+## 常用运维命令（`git:manage.py`）
+| 命令 | 作用 | 示例 |
+|------|------|------|
+| `python3 manage.py status` | 查看容器状态、Nextcloud 状态、ONLYOFFICE 连接检查 | — |
+| `python3 manage.py start` / `stop` / `restart` / `down` | 生命周期管理 | `manage.py start` 启动所有服务 |
+| `python3 manage.py logs [service] --tail 200 --follow` | 查看指定服务日志（service 可选 nextcloud、onlyoffice、db、redis、cron） | `manage.py logs nextcloud --follow` |
+| `python3 manage.py backup [--output PATH]` | 执行完整备份：停机、导出数据库、打包卷、复制 `.env` 与 `docker‑compose.yml` | — |
+| `python3 manage.py reconfigure [--host-ip IP] [--nextcloud-port PORT] [--onlyoffice-port PORT]` | 更新 IP 与端口配置，自动写入 `.env` 并刷新 Nextcloud trusted domains | — |
+
+## 备份策略（依据 `global_guidance_memory:5ed86f53` 与 `manage.py` 实现）
+1. **进入维护模式**：`occ maintenance:mode --on`，确保数据一致性。
+2. **导出 PostgreSQL**：使用 `pg_dump` 将数据库导出至备份目录。
+3. **卷归档**：对 `nextoffice_nextcloud_html`、`nextoffice_nextcloud_data`、`nextoffice_onlyoffice_data`、`nextoffice_onlyoffice_lib` 四个 Docker 卷执行 `tar -czf` 打包。
+4. **保存关键文件**：复制 `.env`（含敏感凭证）与 `docker-compose.yml`。
+5. **退出维护模式**：`occ maintenance:mode --off`。
+> 备份目录默认位于项目根目录的 `backups/<timestamp>`，请务必对其实施访问控制。
+
+## 配置变更与重新部署（参考 `manage.py reconfigure`）
+- 修改 `HOST_IP`、`NEXTCLOUD_PORT`、`ONLYOFFICE_PORT` 后，脚本会自动更新 `.env`、重新启动容器并调用 `occ config:system:set trusted_domains` 与 `occ config:app:set onlyoffice DocumentServerUrl` 完成同步。
+- 如需更改其他环境变量（如数据库密码），请手动编辑 `.env` 并执行 `docker compose up -d` 重新创建容器。
+
+## 日志与故障排查（依据全局工作流 `global_guidance_document:e4fc35f2`）
+- **Docker 超时**：若 `docker exec` 超时，请参考 “Docker Exec 超时” 章节，在 `manage.py` 中已通过 `socket.settimeout(None)` 处理。
+- **FastAPI 异步陷阱**：如自定义扩展使用 FastAPI，请确保不在 `async def` 中调用阻塞 I/O（已在全局经验中提醒）。
+- **代理配置**：若容器内部需要外网访问，确保 Docker Desktop 代理已设为手动 `http://127.0.0.1:7897`（全局经验）。
+
+## 常规维护任务
+- 定期运行 `manage.py backup`，并将备份上传至安全存储。
+- 每次代码改动后更新 `aidocs/project_context.md`（已在全局规则中说明），使用 `type: 中文说明` 格式提交。
+- 关注官方升级公告，若 Nextcloud、ONLYOFFICE 发布安全更新，使用 `docker pull` 拉取新镜像并执行 `docker compose up -d --remove-orphans` 完成滚动升级。
+
+## 参考全局规则与偏好
+| 编号 | 规则/偏好 | 来源 |
+|------|-----------|------|
+| 1 | 开发实施原则（KISS & YAGNI） | `global_guidance_memory:bf88c265-4749-4c50-85bc-4bae25298cd5` |
+| 2 | 项目记忆与 Git 工作流（本地记忆不提交） | `global_guidance_memory:5ed86f53-b53e-4534-8e51-d3a010069d5e` |
+| 3 | 凭证检索工作流 | `global_guidance_document:e4fc35f2-1606-4b79-9c1e-367edeea97d0` |
+| 4 | 全局偏好：使用最简实现 | `global_guidance_document:2b47472d-3ac2-4394-8646-c6bf1c0fc270` |
+| 5 | 语言偏好：使用中文 | `global_guidance_memory:ff34c6eb-6bba-41e5-9e43-ff80941fa823` |
+
+**标签**: ["maintenance", "development", "NextOffice"]

projects/d1932ed6-07d3-4463-a224-8534ffd69a07/curated/development/NextOffice 部署指南.md

@@ -0,0 +1,179 @@
+---
+title: NextOffice 部署指南
+type: curated
+permalink: main/projects/d1932ed6-07d3-4463-a224-8534ffd69a07/curated/development/next-office-部署指南
+stable_id: a4ee5dcf-b0fb-4db7-a8db-ff7faf5b775b
+scope: project
+project_id: d1932ed6-07d3-4463-a224-8534ffd69a07
+workspace_type: development
+usage_profile_id: null
+preference_context: development
+document_type: deployment
+revision: 1
+source_memory_ids: []
+source_checkpoint_ids: []
+source_file_ids: []
+source_git_commit: 346195c0699cb8a1dbf5a9576daad945003e5d10
+source_git_commits:
+- 346195c0699cb8a1dbf5a9576daad945003e5d10
+source_agent_sync_ids: []
+model_connection: Sub2API
+model_name: openai/gpt-oss-120b
+source_count: 25
+source_revisions: {}
+source_dispositions:
+  processed: 25
+  unchanged: 0
+  unsupported: 0
+  skipped: 0
+cited_source_ids:
+- curated_baseline:5bbc6eda-83e0-442d-ab3e-196559cad551
+- curated_baseline:aa86e425-a012-44b5-a805-708f2e077293
+- curated_baseline:847e3e43-85e8-431d-b0f7-7b16211c0da1
+- git:deploy.py
+- git:README.md
+- git:docker-compose.yml
+- git:.env.example
+- git:.gitignore
+- global_guidance_memory:7429c22e-50ff-458a-97c0-423c679904c7
+- global_guidance_memory:1194be51-ee29-47e1-8957-ec2888007db6
+- global_guidance_memory:bf88c265-4749-4c50-85bc-4bae25298cd5
+- global_guidance_memory:3f91189b-11a1-45bb-8357-4f413dc1609d
+- global_guidance_memory:105b328f-4bda-4641-90a7-7282ef156316
+- global_guidance_memory:5ed86f53-b53e-4534-8e51-d3a010069d5e
+- global_guidance_document:d3a20d44-6001-4c88-8772-65dbfac75e6e
+- global_guidance_document:8a861a5f-35c3-4f95-bd5b-6b2297888f56
+- global_guidance_document:6973450e-6ecc-48e3-8cdd-4d7d7707d843
+job_cited_source_ids:
+- curated_baseline:5bbc6eda-83e0-442d-ab3e-196559cad551
+- curated_baseline:aa86e425-a012-44b5-a805-708f2e077293
+- curated_baseline:847e3e43-85e8-431d-b0f7-7b16211c0da1
+- git:deploy.py
+- git:README.md
+- git:docker-compose.yml
+- git:.env.example
+- git:.gitignore
+- global_guidance_memory:7429c22e-50ff-458a-97c0-423c679904c7
+- global_guidance_memory:1194be51-ee29-47e1-8957-ec2888007db6
+- global_guidance_memory:bf88c265-4749-4c50-85bc-4bae25298cd5
+- global_guidance_memory:3f91189b-11a1-45bb-8357-4f413dc1609d
+- global_guidance_memory:105b328f-4bda-4641-90a7-7282ef156316
+- global_guidance_memory:5ed86f53-b53e-4534-8e51-d3a010069d5e
+- global_guidance_document:d3a20d44-6001-4c88-8772-65dbfac75e6e
+- global_guidance_document:8a861a5f-35c3-4f95-bd5b-6b2297888f56
+- global_guidance_document:6973450e-6ecc-48e3-8cdd-4d7d7707d843
+conflicts: []
+supersedes: []
+preferences:
+- statement: 日常交流使用中文（包括文档、代码注释等）
+  level: scenario
+  workspace_types:
+  - development
+  workspace_ids: []
+  source_ids:
+  - global_guidance_memory:7429c22e-50ff-458a-97c0-423c679904c7
+  counterexample_source_ids: []
+  occurrence_count: 1
+  explicit: true
+  confidence: 1.0
+  status: current
+- statement: 开发记忆统一使用 MemRelay 持久管理，禁止本地副本除非用户明确要求
+  level: scenario
+  workspace_types:
+  - development
+  workspace_ids: []
+  source_ids:
+  - global_guidance_memory:1194be51-ee29-47e1-8957-ec2888007db6
+  counterexample_source_ids: []
+  occurrence_count: 1
+  explicit: true
+  confidence: 1.0
+  status: current
+- statement: AI 驱动的记忆同步与 Git 集成默认关闭
+  level: scenario
+  workspace_types:
+  - development
+  workspace_ids: []
+  source_ids:
+  - global_guidance_memory:3f91189b-11a1-45bb-8357-4f413dc1609d
+  counterexample_source_ids: []
+  occurrence_count: 1
+  explicit: true
+  confidence: 1.0
+  status: current
+- statement: 在任何登录、SSH、数据库或 API 调用前先查询 Vaultwarden，唯一匹配则直接使用
+  level: scenario
+  workspace_types:
+  - development
+  workspace_ids: []
+  source_ids:
+  - global_guidance_memory:105b328f-4bda-4641-90a7-7282ef156316
+  counterexample_source_ids: []
+  occurrence_count: 1
+  explicit: true
+  confidence: 1.0
+  status: current
+source_cursor: 292
+source_hash: deb30a6b83a03f25e5a91c6b2d68024ae3de216638efb5597267ac9555bb804f
+prompt_version: 2026-08-12.3
+schema_version: '3'
+curation_job_id: ef181130-6e65-470d-be87-1c06a2de345c
+created_at: '2026-09-02T18:36:53.608654+00:00'
+updated_at: '2026-09-02T18:36:53.609302+00:00'
+tags:
+- deployment
+- development
+- NextOffice
+---
+
+# NextOffice 部署指南
+
+## 项目概览
+- 项目名称：NextOffice（已在 2026‑09‑01 创建）
+- 工作空间类型：development
+- 交付目录：`E:\\Data\\Users\\Administrator\\Desktop\\NextOffice`
+- 采用离线部署包，所有必需镜像已在 `images/nextoffice-images-amd64.tar` 中提供，若缺失将自动在线拉取。
+
+## 关键前置条件
+- 目标服务器必须运行 **Windows + WSL2 + Docker Desktop**（全局指导）`global_guidance_document:6973450e-6ecc-48e3-8cdd-4d7d7707d843`
+- 已安装 **Python 3**（推荐 3.10+）以及 **Docker Engine** 与 **Docker Compose plugin**。
+- 依据全局开发实施原则，保持实现最简（KISS & YAGNI）`global_guidance_memory:bf88c265-4749-4c50-85bc-4bae25298cd5`。
+- 所有凭证在使用前必须先查询 Vaultwarden，且新生成的密码等立即写入密码库 `global_guidance_memory:105b328f-4bda-4641-90a7-7282ef156316`。
+
+## 部署步骤概述（依据 `git:deploy.py`）
+1. **检查前置工具**：`docker version`、`docker compose version`（脚本 `check_prerequisites`）。
+2. **创建或加载配置**：如果 `.env` 已存在则直接使用，否则交互式提示服务器 IP、端口、管理员账号/密码并写入 `ENV_FILE`（`create_or_load_config`）。
+3. **准备镜像**：
+   - 若离线镜像文件存在，使用 `docker load -i` 导入。
+   - 否则拉取基础镜像 `nextcloud:34.0.3-apache` 并拉取其余所需镜像 `onlyoffice/documentserver:9.4.0`、`postgres:17.11-alpine`、`redis:7.4.11-alpine`，随后构建定制 Nextcloud 镜像（`build_nextcloud_image`）。
+4. **启动服务**：`docker compose up -d --remove-orphans`。
+5. **等待服务就绪**：脚本轮询 ONLYOFFICE `http://127.0.0.1:<ONLYOFFICE_PORT>/healthcheck` 与 Nextcloud `http://127.0.0.1:<NEXTCLOUD_PORT>/status.php`，超时 600 秒。
+6. **配置 Nextcloud 与 ONLYOFFICE**：启用 `text`、`viewer`、`onlyoffice` 应用；设置系统语言为 `zh_CN`、关闭默认文件模板目录、清理首次部署示例文件、配置 ONLYOFFICE 连接器以及共享策略。
+7. **完成部署**：输出门户地址、管理员账号以及 ONLYOFFICE 健康检查链接。
+
+## 交付内容快速回顾（`curated_baseline:5bbc6eda-...`）
+- 部署脚本 `deploy.py` 已删除哈希校验相关代码。
+- `manage.py backup` 已不生成 `SHA256SUMS.json`，对应文件已删除。
+- 静态检查全部通过：`python -m py_compile deploy.py manage.py`、`docker compose config --quiet`、`python deploy.py --help`。
+
+## 参考文档与规则
+| 编号 | 内容 | 来源 |
+|------|------|------|
+| 1 | 日常交流使用中文 | `global_guidance_memory:7429c22e-50ff-458a-97c0-423c679904c7` |
+| 2 | 开发记忆统一使用 MemRelay | `global_guidance_memory:1194be51-ee29-47e1-8957-ec2888007db6` |
+| 3 | 开发实施原则（KISS & YAGNI） | `global_guidance_memory:bf88c265-4749-4c50-85bc-4bae25298cd5` |
+| 4 | AI 与 Git 集成默认关闭 | `global_guidance_memory:3f91189b-11a1-45bb-8357-4f413dc1609d` |
+| 5 | 凭证查询与写入规则 | `global_guidance_memory:105b328f-4bda-4641-90a7-7282ef156316` |
+| 6 | 项目记忆与 Git 工作流 | `global_guidance_memory:5ed86f53-b53e-4534-8e51-d3a010069d5e` |
+| 7 | 开发记忆文件位置与提交约定 | `global_guidance_document:d3a20d44-6001-4c88-8772-65dbfac75e6e` |
+| 8 | 跨工作空间技术经验（Docker 代理等） | `global_guidance_document:8a861a5f-35c3-4f95-bd5b-6b2297888f56` |
+| 9 | 项目时间线 | `curated_baseline:847e3e43-85e8-431d-b0f7-7b16211c0da1` |
+|10| 任务清单 | `curated_baseline:aa86e425-a012-44b5-a805-708f2e077293` |
+
+## 相关文件（供引用）
+- `README.md`（部署说明）`git:README.md`
+- `docker-compose.yml`（服务编排）`git:docker-compose.yml`
+- `.env.example`（示例环境变量）`git:.env.example`
+- `.gitignore`（忽略规则）`git:.gitignore`
+
+**标签**: ["deployment", "development", "NextOffice"]

projects/d1932ed6-07d3-4463-a224-8534ffd69a07/curated/development/System Architecture Overview.md

@@ -0,0 +1,112 @@
+---
+title: System Architecture Overview
+type: curated
+permalink: main/projects/d1932ed6-07d3-4463-a224-8534ffd69a07/curated/development/system-architecture-overview
+stable_id: 4f9904fa-0a77-4ea6-9cfd-eb43aa949a54
+scope: project
+project_id: d1932ed6-07d3-4463-a224-8534ffd69a07
+workspace_type: development
+usage_profile_id: null
+preference_context: development
+document_type: architecture
+revision: 1
+source_memory_ids: []
+source_checkpoint_ids: []
+source_file_ids: []
+source_git_commit: 346195c0699cb8a1dbf5a9576daad945003e5d10
+source_git_commits:
+- 346195c0699cb8a1dbf5a9576daad945003e5d10
+source_agent_sync_ids: []
+model_connection: Sub2API
+model_name: openai/gpt-oss-120b
+source_count: 25
+source_revisions: {}
+source_dispositions:
+  processed: 25
+  unchanged: 0
+  unsupported: 0
+  skipped: 0
+cited_source_ids:
+- git:docker-compose.yml
+- git:deploy.py
+- git:README.md
+- global_guidance_document:6973450e-6ecc-48e3-8cdd-4d7d7707d843
+- global_guidance_document:d3a20d44-6001-4c88-8772-65dbfac75e6e
+job_cited_source_ids:
+- git:docker-compose.yml
+- git:deploy.py
+- git:README.md
+- global_guidance_document:6973450e-6ecc-48e3-8cdd-4d7d7707d843
+- global_guidance_document:d3a20d44-6001-4c88-8772-65dbfac75e6e
+conflicts: []
+supersedes: []
+preferences:
+- statement: 遵循 KISS & YAGNI，使用最简单且正确的实现
+  level: workspace
+  workspace_types:
+  - development
+  workspace_ids:
+  - d1932ed6-07d3-4463-a224-8534ffd69a07
+  source_ids:
+  - global_guidance_memory:bf88c265-4749-4c50-85bc-4bae25298cd5
+  counterexample_source_ids: []
+  occurrence_count: 1
+  explicit: true
+  confidence: 1.0
+  status: current
+- statement: 复用已有框架、服务、工具和约定，避免重复实现
+  level: workspace
+  workspace_types:
+  - development
+  workspace_ids:
+  - d1932ed6-07d3-4463-a224-8534ffd69a07
+  source_ids:
+  - global_guidance_memory:bf88c265-4749-4c50-85bc-4bae25298cd5
+  counterexample_source_ids: []
+  occurrence_count: 1
+  explicit: true
+  confidence: 1.0
+  status: current
+source_cursor: 292
+source_hash: deb30a6b83a03f25e5a91c6b2d68024ae3de216638efb5597267ac9555bb804f
+prompt_version: 2026-08-12.3
+schema_version: '3'
+curation_job_id: ef181130-6e65-470d-be87-1c06a2de345c
+created_at: '2026-09-02T18:36:48.074255+00:00'
+updated_at: '2026-09-02T18:36:48.074835+00:00'
+tags:
+- architecture
+- development
+---
+
+# 系统架构概览 (Architecture)
+
+## 主要组件
+| 服务 | Docker 镜像 | 端口 | 说明 |
+|------|------------|------|------|
+| **PostgreSQL** | `postgres:17.11‑alpine` | `5432` (内部) | Nextcloud 数据库，使用 `POSTGRES_` 环境变量配置。 |
+| **Redis** | `redis:7.4.11‑alpine` | `6379` (内部) | 会话与缓存，使用 `REDIS_PASSWORD` 进行保护。 |
+| **ONLYOFFICE DocumentServer** | `onlyoffice/documentserver:9.4.0` | `8081` (外部) | 文档编辑服务，启用 JWT (`ONLYOFFICE_JWT_SECRET`)。 |
+| **Nextcloud (定制镜像)** | `nextoffice/nextcloud:34.0.3-oo10.1.2` | `8080` (外部) | 核心文件管理与协作平台，已在 `deploy.py` 中启用 `text`, `viewer`, `onlyoffice` 三个插件。 |
+| **Cron 容器** | 同上 (nextcloud 镜像) | — | 运行 Nextcloud 定时任务。 |
+
+## 网络布局
+- 两个 Docker 网络：`frontend`（对外暴露端口）和 `backend`（内部服务互通，`internal: true`）。
+- 宿主机通过 `host.docker.internal` 可以访问容器内部服务，符合 **全局工作区概述** 中的代理与网络约定。
+
+## 部署流程概述 (deploy.py)
+1. 检查 Docker 与 Docker Compose 可用。  
+2. 如存在 `images/nextoffice-images-amd64.tar`，使用 `docker load` 导入离线镜像；否则在线拉取基础镜像并在 `build/Dockerfile.nextcloud` 中构建定制镜像。  
+3. 生成 `.env`（或读取已有），写入关键密码、JWT 秘钥等。  
+4. `docker compose up -d` 启动全部服务。  
+5. 等待 ONLYOFFICE 与 Nextcloud 健康检查通过后，使用 `occ` 启用插件、配置语言、默认域、共享策略等。  
+6. 首次运行时清理默认示例文件并写入 `nextoffice_defaults_cleaned` 标记，以防重复清理。
+
+## 配置约定 (全局规则)
+- **KISS & YAGNI**：仅使用必需的服务与环境变量，未引入假设的未来依赖。  
+- **复用已有框架**：`docker-compose.yml` 直接使用官方镜像标签，无额外包装。  
+- **凭证边界**：所有敏感信息均写入 `.env` 并受文件系统权限保护 (`600`)；实际密码仅存于 Vaultwarden，记忆文件 `aidocs/project_context.md` 仅记录名称与用途。
+- **AI / Git 集成默认关闭**：本项目的部署脚本不调用任何模型或本地 Git 仓库，仅在用户明确请求时才执行相应功能。
+
+---
+**参考来源**: `git:docker-compose.yml`, `git:deploy.py`, `git:README.md`, `global_guidance_document:6973450e-6ecc-48e3-8cdd-4d7d7707d843`, `global_guidance_document:d3a20d44-6001-4c88-8772-65dbfac75e6e`