--- 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: git-restore 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: null created_at: '2026-09-02T18:36:56.356802+00:00' updated_at: '2026-09-23T15:05:21.867875+00:00' tags: - maintenance - development - NextOffice restored_from_commit: 6a6a895eafcca6052e81a14fca103a42635dd1c2 --- # 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/`，请务必对其实施访问控制。 ## 配置变更与重新部署（参考 `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"]