Superuser
335 lines
17 KiB
Markdown
335 lines
17 KiB
Markdown
# ALiYunManager 项目上下文 (AI可读)
|
||
|
||
> 本文档供 AI 助手快速理解项目部署环境、架构和服务状态，避免做出与现有环境冲突的操作。
|
||
|
||
---
|
||
|
||
## 一、服务器信息
|
||
|
||
| 项目 | 值 |
|
||
|------|-----|
|
||
| 公网 IP | `8.136.137.59` |
|
||
| 根域名 | `dxz99wyr.cn` |
|
||
| 操作系统 | Ubuntu (5.15.0-174-generic) |
|
||
| SSH 连接命令 | `ssh -i "D:\003_Project\小程序连接.pem" root@8.136.137.59` |
|
||
| SSH 密钥路径 | `D:\003_Project\小程序连接.pem` |
|
||
| 服务器项目路径 | `/opt/ALiYunManager` |
|
||
|
||
---
|
||
|
||
## 二、全量子域名规划
|
||
|
||
### 已部署 / 进行中
|
||
|
||
| 子域名 | 用途 | 类型 | 状态 |
|
||
|--------|------|------|------|
|
||
| `me.dxz99wyr.cn` | 个人简历网站 | 前端 | 🔧 进行中 |
|
||
| `www.dxz99wyr.cn` | 小程序网站 | 前端 | ✅ 使用中 [后续替换到二级域名] |
|
||
| `api-resume.dxz99wyr.cn` | 个人简历后台 API | 后端 | ⏳ 占位，待实现 |
|
||
| `api-miniapp.dxz99wyr.cn` | 小程序后台 API | 后端 | ✅ 已接入真实后端 (:3000) |
|
||
|
||
### 待开发
|
||
|
||
| 子域名 | 用途 | 类型 | 状态 |
|
||
|--------|------|------|------|
|
||
| `img.dxz99wyr.cn` | 图床网站 | 服务 | 📋 待开发 |
|
||
| `dash.dxz99wyr.cn` | 服务监控网站 | 服务 | 🔧 部署中（详见 `Dash.md`） |
|
||
| `logs.dxz99wyr.cn` | 日志监控网站 | 服务 | 📋 待开发 |
|
||
| `git.dxz99wyr.cn` | 私有 Git 仓库 + CI/CD | 服务 | 🔧 部署中（详见 `Git.md`） |
|
||
|
||
> DNS A 记录：所有子域名均指向 `8.136.137.59`，已经在阿里云域名控制台配置。
|
||
>
|
||
> **ICP 备案合规要求**：所有涉及二级域名对外展示的页面，**一律在页面底部中间位置**添加 ICP 备案号 `浙ICP备2026030774号-1`，并链接到 `https://beian.miit.gov.cn`。这是法律合规要求，新增任何服务时不可遗漏。
|
||
|
||
### 待开发服务说明
|
||
|
||
**1. 图床网站 `img.dxz99wyr.cn`**
|
||
- 用途：存储个人网站（me.dxz99wyr.cn）上传的图片内容，提供图片外链
|
||
- 需要：图片上传接口、存储管理、访问权限控制
|
||
|
||
**2. 服务监控网站 `dash.dxz99wyr.cn`**
|
||
- 用途：在线监控服务器 CPU、内存、磁盘使用率
|
||
- 监控各 Docker 容器的运行状态（up/down/restart）
|
||
- 监控系统各端口的占用状态、对应服务
|
||
- 可选方案：Grafana + Prometheus、或轻量自建面板
|
||
|
||
**3. 日志网站 `logs.dxz99wyr.cn`**
|
||
- 用途：汇总展示所有 Docker 容器的运行日志
|
||
- 提供历史和实时日志查看
|
||
- 支持按服务、时间过滤
|
||
- 可选方案：ELK (Elasticsearch + Logstash + Kibana)、Grafana Loki、或自建简易面板
|
||
|
||
**4. 私有 Git 仓库 `git.dxz99wyr.cn`**
|
||
- 用途：存档所有项目的源代码（包括本 ALiYunManager 项目）
|
||
- 配套 CI/CD：配置 Git Webhook + 脚本，实现 `git push` 后自动拉取代码并部署到对应服务，不再需要手动 ssh 部署
|
||
- 可选方案：Gitea（轻量）、GitLab CE、Gogs
|
||
|
||
---
|
||
|
||
## 三、端口分配（关键：防止冲突）
|
||
|
||
### 对外网开放的端口
|
||
|
||
| 端口 | 用途 | 备注 |
|
||
|------|------|------|
|
||
| `22` | SSH | 必须保持 |
|
||
| `80` | HTTP 入口 | 由 **beian-nginx**（现有）占用 |
|
||
| `443` | HTTPS 入口 | 由 **beian-nginx**（现有）占用 |
|
||
|
||
### 内部端口（不对外网）
|
||
|
||
| 端口 | 用途 | 备注 |
|
||
|------|------|------|
|
||
| `8080` | main-nginx HTTP | Docker 容器内 80 → 宿主机 8080 |
|
||
| `8443` | main-nginx HTTPS | Docker 容器内 443 → 宿主机 8443 |
|
||
| `3000` | 小程序后端 | `quanyixiaozhushou-app`，仅本地回环访问 |
|
||
|
||
### 端口冲突规则
|
||
|
||
- **绝对不要占用 80/443** — 已被 beian-nginx 使用，新增服务必须挂到 main-nginx 后面（通过 Docker 网络内部 80 通信）
|
||
- **绝对不要占用 8080** — 已被 main-nginx 映射使用
|
||
- **绝对不要暴露 3000 到外网** — 小程序后端已关闭外网访问，仅走本地回环
|
||
- 新增服务容器内部一律使用 `80` 端口，通过 Docker 网络互通，**不要额外映射宿主机端口**
|
||
- **新增待开发服务（img/dash/logs/git）同理**，全部挂到 main-nginx 后面，内部 80 通信，不暴露新端口到外网
|
||
|
||
---
|
||
|
||
## 四、现有 Nginx 链路（两层代理）
|
||
|
||
```
|
||
外网请求
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ beian-nginx (宿主机 :80/:443) │ ← 第1层：入口
|
||
│ 容器名: beian-nginx │
|
||
│ 所属网络: beian-docker_default │
|
||
│ │
|
||
│ 目前已配置中转: │
|
||
│ ✅ me.dxz99wyr.cn → :8080 │
|
||
│ ✅ www.dxz99wyr.cn → :8080 │
|
||
│ ✅ api-resume.dxz99wyr.cn → :8080 │
|
||
│ ✅ api-miniapp.dxz99wyr.cn → :8080 │
|
||
│ ✅ git.dxz99wyr.cn → :8080 │
|
||
│ ✅ dash.dxz99wyr.cn → :8080 │
|
||
│ ✅ /quanyi → 静态页面 (原有服务) │
|
||
└──────────────┬──────────────────────────────────────────┘
|
||
│ 中转请求到 172.19.0.1:8080 (Docker网关=宿主机)
|
||
▼
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ main-nginx (Docker :8080/:8443) │ ← 第2层：分发
|
||
│ 容器名: main-nginx │
|
||
│ 所属网络: aliyun-app-network │
|
||
│ │
|
||
│ 路由表 (已配置): │
|
||
│ me.dxz99wyr.cn → resume-web:80 │
|
||
│ www.dxz99wyr.cn → miniapp-web:80 │
|
||
│ api-resume.dxz99wyr.cn → resume-api:80 │
|
||
│ api-miniapp.dxz99wyr.cn → host.docker.internal:3000 │
|
||
│ │
|
||
│ 路由表 (待添加，新服务上线时): │
|
||
│ img.dxz99wyr.cn → img-service:80 │
|
||
│ dash.dxz99wyr.cn → dash-service:80 │
|
||
│ logs.dxz99wyr.cn → logs-service:80 │
|
||
│ git.dxz99wyr.cn → git-service:80 │
|
||
└──────────────┬──────────────────────────────────────────┘
|
||
│ Docker 内部网络
|
||
▼
|
||
┌──────────┼──────────┬──────────┐
|
||
│ │ │ │
|
||
resume-web miniapp-web resume-api miniapp-api
|
||
(进行中) (使用中) (占位) (→宿主机:3000)
|
||
```
|
||
|
||
### 关键理解
|
||
|
||
- **beian-nginx 是真正的入口**，main-nginx 只在内部做二级分发
|
||
- **beian-nginx 配置文件位置**: `/opt/beian-docker/nginx.conf`（映射到容器内 `/etc/nginx/conf.d/default.conf`）
|
||
- **修改 beian-nginx 前必须先备份**: 备份文件在 `/opt/beian-docker/nginx.conf.bak`
|
||
- 重载 beian-nginx: `docker exec beian-nginx nginx -t && docker exec beian-nginx nginx -s reload`
|
||
|
||
---
|
||
|
||
## 五、Docker 容器清单
|
||
|
||
| 容器名 | 镜像 | 网络 | 端口映射 | 说明 |
|
||
|--------|------|------|----------|------|
|
||
| `beian-nginx` | nginx | beian-docker_default | 80:80, 443:443 | **现有，勿动基础配置** |
|
||
| `main-nginx` | nginx:alpine | aliyun-app-network | 8080:80, 8443:443 | 主 Nginx，本项目管理 |
|
||
| `resume-web` | nginx:alpine | aliyun-app-network | 无(内部80) | 个人简历网站（进行中） |
|
||
| `miniapp-web` | nginx:alpine | aliyun-app-network | 无(内部80) | 小程序网站（使用中） |
|
||
| `resume-api` | nginx:alpine | aliyun-app-network | 无(内部80) | 个人简历后台（占位） |
|
||
| `miniapp-api` | nginx:alpine | aliyun-app-network | 无(内部80) | 小程序后台占位容器 |
|
||
| `quanyixiaozhushou-app` | 自有镜像 | beian-docker_default | 3000:3000 | **现有小程序后端，勿动** |
|
||
| `quanyixiaozhushou-mongo` | mongo | beian-docker_default | 27018:27017 | **现有 MongoDB，勿动** |
|
||
|
||
### Docker 网络
|
||
|
||
| 网络名 | 类型 | 用途 |
|
||
|--------|------|------|
|
||
| `aliyun-app-network` | bridge | 本项目所有服务容器互通 |
|
||
| `beian-docker_default` | bridge | 现有 beian-nginx 及小程序后端 |
|
||
|
||
> **注意**: main-nginx 通过 `extra_hosts: host.docker.internal:host-gateway` 访问宿主机端口（如 3000），不需要两个网络互通。
|
||
|
||
---
|
||
|
||
## 六、项目文件结构
|
||
|
||
```
|
||
ALiYunManager/
|
||
├── .env # 环境变量（域名+端口），修改后需重启
|
||
├── .env.example # 环境变量模板
|
||
├── docker-compose.yml # 完整部署（main-nginx + 4个服务）
|
||
├── docker-compose.main-nginx-only.yml # 仅主 Nginx（各服务独立部署时用）
|
||
├── docker-compose.override.yml # 开发环境覆盖（自动加载）
|
||
├── deploy.sh # 一键部署脚本
|
||
├── Makefile # 常用命令快捷方式
|
||
├── nginx/
|
||
│ ├── nginx.conf # 主 Nginx 核心配置（一般不改）
|
||
│ ├── conf.d/
|
||
│ │ ├── resume-web.conf # me.dxz99wyr.cn → resume-web:80
|
||
│ │ ├── miniapp-web.conf # www.dxz99wyr.cn → miniapp-web:80
|
||
│ │ ├── resume-api.conf # api-resume.dxz99wyr.cn → resume-api:80
|
||
│ │ ├── miniapp-api.conf # api-miniapp.dxz99wyr.cn → host.docker.internal:3000
|
||
│ │ ├── ssl-template.conf # HTTPS 配置模板（按需取消注释）
|
||
│ │ └── port-based-example.conf # 基于端口的备选方案模板
|
||
│ ├── ssl/ # SSL 证书目录（.gitignore 排除）
|
||
│ └── logs/ # Nginx 日志目录
|
||
├── services/
|
||
│ ├── resume-web/ # 个人简历前端（进行中）
|
||
│ │ ├── html/index.html # 占位页面 → 替换为真实简历
|
||
│ │ ├── nginx.conf # 内部 Nginx 配置
|
||
│ │ ├── Dockerfile # 前端 Dockerfile
|
||
│ │ └── docker-compose.yml # 独立部署配置
|
||
│ ├── miniapp-web/ # 小程序前端（使用中）
|
||
│ ├── resume-api/ # 个人简历后台（占位）
|
||
│ │ ├── nginx.conf # 内部 Nginx（占位）
|
||
│ │ ├── Dockerfile # 模板，含 Node/Python/Go 示例
|
||
│ │ └── docker-compose.yml # 独立部署配置
|
||
│ └── miniapp-api/ # 小程序后台（占位 → 实际走宿主机3000）
|
||
└── scripts/
|
||
├── init-server.sh # 新服务器初始化（安装 Docker 等）
|
||
├── setup-ssl.sh # SSL 证书申请（Certbot）
|
||
├── update-service.sh # 更新单个服务
|
||
├── backup.sh # 备份配置和证书
|
||
└── logrotate-nginx # 日志轮转配置
|
||
```
|
||
|
||
---
|
||
|
||
## 七、环境变量（.env 当前值）
|
||
|
||
```
|
||
DOMAIN_RESUME_WEB=me.dxz99wyr.cn
|
||
DOMAIN_MINIAPP_WEB=www.dxz99wyr.cn
|
||
DOMAIN_RESUME_API=api-resume.dxz99wyr.cn
|
||
DOMAIN_MINIAPP_API=api-miniapp.dxz99wyr.cn
|
||
NGINX_HTTP_PORT=8080
|
||
NGINX_HTTPS_PORT=8443
|
||
TZ=Asia/Shanghai
|
||
|
||
# -- 待开发服务（上线时取消注释） --
|
||
# DOMAIN_IMG=img.dxz99wyr.cn
|
||
# DOMAIN_DASHBOARD=dash.dxz99wyr.cn
|
||
# DOMAIN_LOGS=logs.dxz99wyr.cn
|
||
# DOMAIN_GIT=git.dxz99wyr.cn
|
||
```
|
||
|
||
---
|
||
|
||
## 八、操作注意事项（AI 助手必读）
|
||
|
||
### 全局铁律（所有新增内容必须遵守）
|
||
|
||
**规则 1 — 文件存储路径**
|
||
- 所有新增项目的文件**一律存储在 `/home/` 目录下**，子目录以项目名命名（如 `/home/Git/`、`/home/Dash/`）。
|
||
- **能放在 Docker 容器里的，就不要放在宿主机上**。配置文件、脚本等通过 volume 挂载进容器，不要在宿主机直接运行。
|
||
|
||
**规则 2 — 脚本后台运行 & 开机自启**
|
||
- 所有需要持续运行的脚本/服务，启动时必须使用后台方式（nohup、screen、tmux 或 Docker 容器），**保证关闭 SSH 会话后不受影响**。
|
||
- 必须配置**开机自启动**，云服务器重启后自动恢复运行。
|
||
- Docker 容器：`restart: always`（已在所有 docker-compose.yml 中统一配置）
|
||
- 宿主机脚本/进程：必须配置 systemd service 或 crontab `@reboot` 条目
|
||
- Docker 守护进程自启：`systemctl enable docker`（已由 `scripts/init-server.sh` 配置）
|
||
|
||
**规则 3 — SSL 证书自动化**
|
||
- 所有涉及在线 Web 访问的服务，**必须通过 Certbot 自动配置 SSL 证书**（参考 `scripts/setup-ssl.sh`）。
|
||
- 证书到期前 3 天**自动续期**，通过 crontab 定时任务实现：
|
||
```
|
||
0 3 * * * certbot renew --quiet --deploy-hook 'docker exec main-nginx nginx -s reload'
|
||
```
|
||
- 新增服务上线时，同步更新 certbot 证书覆盖的域名列表。
|
||
|
||
**规则 4 — 优先使用国内镜像源**
|
||
- 所有涉及下载的操作（pip install、npm install、apt-get、apk add、docker pull、git clone 等），**优先查找并使用国内镜像源**，提升下载速度。
|
||
- 常用国内源：
|
||
- Docker Hub：阿里云容器镜像服务、腾讯云 `mirror.ccs.tencentyun.com`
|
||
- Python pip：清华 `pypi.tuna.tsinghua.edu.cn`、阿里 `mirrors.aliyun.com/pypi/simple`
|
||
- Node.js npm：淘宝 `registry.npmmirror.com`
|
||
- Alpine apk：清华 `mirrors.tuna.tsinghua.edu.cn/alpine`、中科大 `mirrors.ustc.edu.cn/alpine`
|
||
- Debian/Ubuntu apt：阿里 `mirrors.aliyun.com/ubuntu`、清华 `mirrors.tuna.tsinghua.edu.cn/ubuntu`
|
||
- Git clone：优先使用 Docker 内网 HTTP（如 `http://gitea:3000/...`），不走外网
|
||
- Dockerfile 中 `RUN` 命令在安装包前先替换为国内源。
|
||
|
||
**规则 5 — 服务修改隔离**
|
||
- 修改某一服务时，**不准修改非该服务的内容**，包括但不限于：其他服务的网页页面、nginx 配置、反向代理规则、重定向、Docker 容器配置。
|
||
- 如果发现其他服务存在问题，**一律先告知用户**，不得自行改动。
|
||
- **用户未正面答复确认的**（如"知道了"、"先不管"、"改"等），AI 助手在之后的每次会话中，**都需要主动提醒用户**，直到用户给出正面答复为止。
|
||
|
||
### 绝对不能违反的合规要求
|
||
|
||
0. **所有二级域名的页面底部中间必须显示 ICP 备案号**：`浙ICP备2026030774号-1`，并链接到 `https://beian.miit.gov.cn`。新增任何服务时不可遗漏。
|
||
|
||
### 绝对不能做的事
|
||
|
||
1. **不要修改 beian-nginx 的基础配置**（default_server、/quanyi 路径等），只能追加新的 server 块做域名中转
|
||
2. **不要改动 `nginx/nginx.conf`**（主 Nginx 核心配置），除非明确需要调整全局参数
|
||
3. **不要将 3000、8080、8443 端口暴露到外网**
|
||
4. **不要删除或停用 beian-nginx、quanyixiaozhushou-app、quanyixiaozhushou-mongo 容器**
|
||
5. **不要在 main-nginx 容器内直接改配置**，应修改本地 `nginx/conf.d/*.conf` 文件后重载
|
||
|
||
### 新增服务时的标准流程
|
||
|
||
1. 在 `/home/<项目名>/` 下创建项目目录（遵守规则 1）
|
||
2. 所有服务逻辑放入 Docker 容器，宿主机仅保留 docker-compose.yml 和配置文件（遵守规则 1）
|
||
3. 在 `nginx/conf.d/` 下创建对应的反向代理 `.conf` 文件（参考已有配置）
|
||
4. 在 `.env` 中添加新子域名变量
|
||
5. 在本项目 `docker-compose.yml` 中添加新服务定义，确保 `restart: always`（遵守规则 2）
|
||
6. 在 beian-nginx 中追加对应的中转 server 块
|
||
7. 在阿里云 DNS 添加子域名 A 记录
|
||
|
||
### 修改 beian-nginx 配置的标准流程
|
||
|
||
```bash
|
||
# 1. 备份当前配置
|
||
cp /opt/beian-docker/nginx.conf /opt/beian-docker/nginx.conf.bak.$(date +%Y%m%d)
|
||
|
||
# 2. 编辑配置（在 server 块区域追加新的域名中转）
|
||
vim /opt/beian-docker/nginx.conf
|
||
|
||
# 3. 测试配置
|
||
docker exec beian-nginx nginx -t
|
||
|
||
# 4. 重载
|
||
docker exec beian-nginx nginx -s reload
|
||
```
|
||
|
||
---
|
||
|
||
## 九、待办清单
|
||
|
||
| # | 事项 | 优先级 | 所属服务 |
|
||
|---|------|--------|----------|
|
||
| 1 | beian-nginx 补充中转配置（me、www、api-resume） | ✅ 已完成 | 基础设施 |
|
||
| 2 | 替换 `services/resume-web/html/` 为真实简历代码 | 🔴 高 | me.dxz99wyr.cn |
|
||
| 3 | 实现个人简历后台真实后端代码（`services/resume-api/`） | 🟡 中 | api-resume.dxz99wyr.cn |
|
||
| 4 | 配置 HTTPS / SSL 证书（运行 `./scripts/setup-ssl.sh`） | 🟡 中 | 全部 |
|
||
| 5 | 新建图床服务 `img.dxz99wyr.cn` | 🟢 低 | img |
|
||
| 6 | 部署监控面板 `dash.dxz99wyr.cn`（Dashy + Netdata + 状态API） | 🔧 进行中 | dash |
|
||
| 7 | 新建日志面板 `logs.dxz99wyr.cn`（汇总所有 Docker 日志） | 🟢 低 | logs |
|
||
| 8 | 部署私有 Git 仓库 `git.dxz99wyr.cn`（Gitea + Webhook 自动部署） | 🔧 进行中 | git |
|
||
| 9 | 配置 Git Webhook + 自动部署流水线（git push → 自动拉代码部署） | 🔧 进行中 | git/CICD |
|
||
| 10 | 配置日志轮转 (logrotate) | 🟢 低 | 基础设施 |
|
||
| 11 | 小程序网站后续替换为二级域名 | 🟢 低 | www.dxz99wyr.cn |
|