新贡献者本地启动后端时遇到的多个问题汇总

[F1sh2712]

背景

按照 README 的"快速开始"指南从零搭建本地开发环境时,遇到了一系列阻塞问题。
作为一个新贡献者,从 git clone 到成功启动后端 + 通过 /auth/login 接口
登录,中间踩了 5 个坑。希望这份汇总能帮助维护者了解新人入门体验,
并改善后续贡献者的上手成本。

环境

• OS: Windows 11
• JDK: 25.0.2 (Eclipse Temurin)
• Maven: 3.9.12 (通过 mvnw)
• Docker Desktop (latest)
• IDE: IntelliJ IDEA 2025.3

遇到的问题

问题 1: README 引用了不存在的 redis 服务

执行 README 中的命令:

```
docker compose up -d postgres redis
```

报错:

```
no such service: redis
```

docker-compose.yml 中只定义了 backend、postgres、pgadmin、pg-backup
四个服务,Redis 已被移除。

建议修复: 更新 README,改为 docker compose up -d postgres,
并移除注释中"启动 Redis 7"的部分。

---

问题 2: docker-compose.yml 数据卷挂载路径不兼容 PostgreSQL 18

启动 postgres 容器后无限重启,日志报:

```
Error: in 18+, these Docker images are configured to store database data
in a format which is compatible with "pg_ctlcluster" (specifically,
using major-version-specific directory names).
The suggested container configuration for 18+ is to place a single mount
at /var/lib/postgresql which will then place PostgreSQL data in a subdirectory.
```

PostgreSQL 18 修改了 Docker 镜像的数据存储路径规范,
要求挂载到 /var/lib/postgresql(父目录),而当前 docker-compose.yml
挂载的是旧路径 /var/lib/postgresql/data。

建议修复: 修改 docker-compose.yml 中 postgres 服务的 volumes 配置:

```yaml

修改前

• involution-postgres-data:/var/lib/postgresql/data

修改后

• involution-postgres-data:/var/lib/postgresql
  ```

---

问题 3: .env.example 默认配置指向 Neon 云数据库,本地开发无法直接使用

.env.example 中 PGHOST、SPRING_DATASOURCE_URL 等默认指向 Neon
云端占位符地址(ep-xxxx.aws.neon.tech),且 PGUSER=neondb_owner
与 Docker 容器创建的本地用户 involution 不匹配。

任何按 README 走的新人(无 Neon 账号)在本地都需要先理解这层关系
并手动改 .env,才能让后端连上本地 Docker 的 PostgreSQL。

建议修复: 让 .env.example 默认配置指向本地 Docker(开箱即用),
Neon 配置作为可选注释。例如:

```env

--- 数据库(默认本地 Docker)---

PGHOST=localhost
PGUSER=involution
PGPASSWORD=change_me
PGDATABASE=involution_hell
PGSSLMODE=disable
SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/involution_hell
SPRING_SQL_INIT_MODE=always

--- 如果使用 Neon 云数据库,注释上面并启用以下配置 ---

PGHOST=ep-xxxx.ap-southeast-2.aws.neon.tech

PGUSER=neondb_owner

...

```

---

问题 4: README 未说明 ./mvnw spring-boot:run 不会自动加载 .env

./mvnw spring-boot:run 直接启动的 Java 进程不会读取 .env 文件,
导致 PGUSER、PGPASSWORD 等环境变量缺失,启动时报:

```
The server requested SCRAM-based authentication, but no password was provided.
```

新人很难联想到这一点。需要文档明确说明加载 .env 的方法
(macOS/Linux 用 source 或 direnv,Windows PowerShell 需手动设置或写脚本,
IDE 用户可用 EnvFile 插件)。

建议修复: 在 README "启动后端服务"章节增加加载环境变量的说明。

---

问题 5: user_accounts 表结构与 Java 代码不同步

数据库初始化后(由 docker/init-db/init.sql 创建)的 user_accounts 表
缺少 avatar_url、email、github_id 三个列,导致后端启动时
SharedLinkService 初始化失败:

```
The column name avatar_url was not found in this ResultSet.
The column name email was not found in this ResultSet.
```

对比三处定义:

• JdbcUserAccountRepository.java(rowMapper)期望 11 列
• src/main/resources/schema.sql 定义了正确的 10 列(含 avatar_url、email、github_id)
• docker/init-db/init.sql 实际创建的表只有 8 列(缺三个)

init.sql 与 schema.sql / Java 代码失去同步。

建议修复: 同步 docker/init-db/init.sql 中 user_accounts 表定义,
补齐 avatar_url VARCHAR(500)、email VARCHAR(255)、github_id BIGINT UNIQUE 三列。
长期来看,建议引入 Flyway 或 Liquibase 管理 schema 变更,避免类似问题再次发生。

我能帮忙的部分

我已经在本地完整跑通了项目并验证了所有解决方案。如果维护者确认这些是
需要修复的问题,我愿意为以下问题提交 PR:

• 问题 1:更新 README 移除 redis 引用
• 问题 2:修正 docker-compose.yml PostgreSQL 18 挂载路径
• 问题 3:.env.example 默认本地 Docker 配置
• 问题 4:README 增加 .env 加载说明
• 问题 5:同步 init.sql(需维护者确认字段定义是否完整)

谢谢!

[longsizhuo]

收到, 我会确认你说的这些问题, 的确现在init阶段还没有从0 验证过