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

2026-09-23 22:38:40 +08:00
parent 5313fcee7a
commit 6a6a895eaf
638 changed files with 29816 additions and 1 deletions
@@ -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"]