113 lines
4.8 KiB
Markdown
113 lines
4.8 KiB
Markdown
---
|
||
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` |