# project-manager

**Repository Path**: Kumono/project-manager

## Basic Information

- **Project Name**: project-manager
- **Description**: ????????
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-06
- **Last Updated**: 2026-09-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 简易项目管理系统

面向小团队的中文项目管理网站。账号可同时加入多个小队，线索与正式项目可归属个人空间或小队共享空间，并支持邮件邀请、队长/管理员角色、待办、展示版本、项目资料、日历与提醒、财务字段、审计日志，以及 Excel/PDF 导出。系统只管理项目资料，不托管项目源码、代码仓库、构建或部署流程。

## 目录结构

```text
backend/                 Java 21 + Spring Boot REST API
frontend/                Vue 3 + Vite 前端与 Nginx 配置
deploy/infrastructure/   MySQL、Redis、MinIO、备份任务
deploy/application/      后端、前端/Nginx、Certbot
```

基础设施和网站是两个独立的 Compose 项目，通过外部网络 `project-manager-net` 通信；删除或重建网站容器不会影响 MySQL、MinIO 数据卷。

## 本地开发

需要 Java 21、Maven 3.9+、Node.js 22、pnpm 11、Docker Desktop。

1. 启动本地基础设施（示例配置只用于开发，请勿用于生产）：

   ```powershell
   cd deploy/infrastructure
   Copy-Item .env.example .env
   docker compose --env-file .env up -d mysql redis minio
   ```

2. 推荐在项目根目录运行一键开发启动脚本。后端固定使用 Java 21 容器，不受系统默认 JDK 影响：

   ```powershell
   .\start-dev.ps1
   ```

   脚本会复用 `project-manager-maven-cache` Docker 卷、启动后端和前端，并等待后端健康检查通过。默认后端端口为 `18081`，Vite 已将 `/api` 代理到该端口。

   如需直接启动后端，启动前将密码和 SMTP 参数改成与本地环境一致，并确保当前 `JAVA_HOME` 指向 Java 21：

   ```powershell
   cd backend
   $env:DB_PASSWORD='change-this-mysql-password'
   $env:REDIS_PASSWORD='change-this-redis-password'
   $env:MINIO_ACCESS_KEY='project-manager-minio'
   $env:MINIO_SECRET_KEY='change-this-minio-password'
   $env:SMTP_HOST='smtp.example.com'
   $env:SMTP_PORT='587'
   $env:SMTP_USERNAME='noreply@example.com'
   $env:SMTP_PASSWORD='change-this-smtp-password'
   $env:SMTP_AUTH='true'
   $env:SMTP_STARTTLS='true'
   mvn spring-boot:run
   ```

3. 启动前端：

   ```powershell
   cd frontend
   corepack enable
   pnpm install --frozen-lockfile
   pnpm dev
   ```

访问 `http://localhost:5173`。Vite 会把 `/api` 代理到 `http://localhost:18081`。首次启动会依据环境变量创建初始管理员，并自动建立默认状态与 MinIO 私有存储桶。

## 生产部署

部署前需要准备两个指向服务器的 DNS 记录：主站域名和文件域名。文件域名只用于权限校验后生成的短期 MinIO 签名地址。

1. 配置并启动基础设施：

   ```bash
   cd deploy/infrastructure
   cp .env.example .env
   # 编辑 .env，替换全部示例密码、SMTP 和管理员告警邮箱
   docker compose --env-file .env up -d --build
   docker compose --env-file .env ps
   ```

2. 配置并启动网站：

   ```bash
   cd ../application
   cp .env.example .env
   # 数据库、Redis、MinIO 凭据必须与基础设施一致；同时填写域名和初始管理员
   docker compose --env-file .env up -d --build
   docker compose --env-file .env ps
   ```

Nginx 会先以 HTTP 模式启动并响应 ACME challenge；Certbot 获得同时覆盖主站和文件域名的证书后，Nginx 自动切换到 HTTPS。生产环境务必使用高强度、互不相同的密码，并限制 MinIO 管理端口和数据库端口的公网访问。

常用命令：

```bash
# 查看日志
docker compose --env-file .env logs -f --tail=200

# 仅重建网站（在 deploy/application 中）
docker compose --env-file .env up -d --build

# 停止网站；不会删除基础设施数据卷
docker compose --env-file .env down
```

除非明确要永久清空数据，否则不要对基础设施执行 `docker compose down -v`。

## 备份与恢复

基础设施中的 `backup` 服务启动后立即备份一次，此后每 24 小时备份 MySQL 和 MinIO。备份使用 Restic 加密，默认写入宿主机 `BACKUP_DIR`，保留 30 天内的快照；Redis 不备份。失败邮件优先发送给数据库中所有启用的管理员，数据库不可用时回退到 `ADMIN_EMAILS`。

手动备份（在 `deploy/infrastructure` 中）：

```bash
docker compose --env-file .env exec backup /usr/local/bin/backup.sh
docker compose --env-file .env exec backup restic snapshots --tag project-manager
```

恢复会覆盖当前数据库和同名 MinIO 对象。先停止网站写入和定时备份，再明确确认：

```bash
cd deploy/application
docker compose --env-file .env stop backend

cd ../infrastructure
docker compose --env-file .env stop backup
docker compose --env-file .env run --rm \
  -e RESTORE_CONFIRM=YES \
  --entrypoint /usr/local/bin/restore.sh backup
docker compose --env-file .env start backup

cd ../application
docker compose --env-file .env start backend
```

恢复后应登录并抽查项目、附件下载和导出。`RESTIC_REPOSITORY` 已独立配置，未来可按 Restic 规范改为远程对象存储仓库；第一版建议保持本地独立挂载目录。

## 测试与构建

后端单元测试和 Testcontainers 集成测试（需要可用的 Docker）：

```powershell
cd backend
mvn test
mvn -DskipTests package
```

前端测试、生产构建和双视口 E2E：

```powershell
cd frontend
pnpm test
pnpm build
pnpm exec playwright install chromium
pnpm test:e2e
```

运行 E2E 前需保持前端开发服务器运行；可通过 `E2E_BASE_URL` 指向其他已部署环境。检查 Compose 配置和镜像：

```bash
cd deploy/infrastructure
docker compose --env-file .env.example config --quiet
docker compose --env-file .env.example build

cd ../application
docker compose --env-file .env.example config --quiet
docker compose --env-file .env.example build
```

## 主要环境变量

- 基础服务：`MYSQL_*`、`REDIS_PASSWORD`、`MINIO_*`
- 网站入口：`DOMAIN`、`FILES_DOMAIN`、`ACME_EMAIL`
- 邮件：`SMTP_*`、`MAIL_FROM`
- 初始管理员：`INITIAL_ADMIN_EMAIL`、`INITIAL_ADMIN_PASSWORD`、`INITIAL_ADMIN_NAME`
- 备份：`BACKUP_DIR`、`BACKUP_PASSWORD`、`RESTIC_REPOSITORY`、`ADMIN_EMAILS`

完整示例分别见 `deploy/infrastructure/.env.example` 和 `deploy/application/.env.example`。

## 免费自托管 CI/CD

项目使用 Gitee Webhook 触发服务器上的自托管流水线，不依赖付费的 Gitee Go。`main` 分支收到推送后：

1. Webhook 服务验证 Gitee 密钥并登记提交；
2. 服务器通过只读部署密钥拉取对应提交；
3. 发布前优先执行一次 MySQL 与 MinIO 的 Restic 备份并记录最新快照；备份服务不可用时至少生成独立的 MySQL 压缩备份；
4. Docker 构建同时完成后端编译和前端类型检查、生产构建；
5. 网站主体 Compose 更新并等待后端健康检查；
6. 备份、构建或健康检查失败时停止发布，应用更新失败时恢复上一版本，成功后保留最近五个版本。

相关文件位于 `deploy/ci/`。服务器敏感配置保存在 `/opt/project-manager/shared/`，不会提交到仓库。
基础设施 Compose 独立运行，自动发布不会修改 MySQL、Redis、MinIO 或其数据卷。部署日志写入
`/var/log/project-manager-deploy.log`。