---
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: git-restore
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: null
created_at: '2026-09-02T18:36:48.074255+00:00'
updated_at: '2026-09-23T15:05:27.361872+00:00'
tags:
- architecture
- development
restored_from_commit: 6a6a895eafcca6052e81a14fca103a42635dd1c2
---

# 系统架构概览 (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`