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

---
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/<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"]