134 lines
8.3 KiB
Markdown
134 lines
8.3 KiB
Markdown
# 部署与配置变更日志
|
||
|
||
> 记录**影响部署方式、配置项、运维命令**的变更。纯功能/界面变更记录见 `docs/sdd/releases/`。
|
||
> 约定：新变更写在最上方；每条必须写清「变更 / 原因 / 影响 / 迁移动作」。
|
||
|
||
---
|
||
|
||
## v1.0.0（待发布：需 `git tag v1.0.0`）
|
||
|
||
### 1. 仓库脚本统一迁移到 `scripts/`
|
||
|
||
- **变更**：根目录的部署/启动脚本全部移入 `scripts/`，新增一键启动与停止脚本。
|
||
|
||
| 旧位置 | 新位置 | 说明 |
|
||
| --- | --- | --- |
|
||
| `./deploy.sh` | `./scripts/deploy.sh` | 部署脚本保留，路径变更 |
|
||
| — | `./scripts/start.sh` | **新增**：本地一键启动（后端 + 前端 + 探活） |
|
||
| — | `./scripts/stop.sh` | **新增**：一键停止本地服务 |
|
||
| `backend/scripts/{init_database.sql,migrate_*.sql,add_*.py,check_*.py,…}` | 删除 | 过期的一次性脚本/SQL，初始化与迁移链路见 `docs/database.md` |
|
||
| `fix_docker_deployment.sh` | 删除 | 针对已不存在的旧 compose 结构 |
|
||
|
||
- **原因**：根目录脚本混杂、命名不一致，历史一次性脚本已与新 schema 脱节，容易误执行。
|
||
- **影响**：所有引用 `./deploy.sh` 的命令、文档、CI 需改为 `./scripts/deploy.sh`。
|
||
- **迁移动作**：
|
||
```bash
|
||
./scripts/deploy.sh --help # 查看可用子命令
|
||
./scripts/start.sh # 本地开发一键启动
|
||
```
|
||
|
||
### 2. Compose 与 `.env` 配置项收敛
|
||
|
||
- **变更**：
|
||
- `docker-compose.yml` 移除废弃的顶层 `version: '3.8'` 字段。
|
||
- 移除前端镜像构建参数 `VITE_API_BASE_URL`（前端代码从未读取该变量）。
|
||
- `.env.example` 移除 `VITE_API_BASE_URL`，改为注释说明前端固定请求同源 `/api/v1`。
|
||
- **原因**：前端 API 地址固定为相对路径 `/api/v1`（开发由 vite `server.proxy` 转发，容器内由 `frontend/nginx.conf` 反代到 compose 服务 `backend`）。保留该变量会让人以为可以改前端 API 域名，实际compose默认值会直接产出坏产物。
|
||
- **影响**：升级后重新 `build` 前端镜像即可；`.env` 中残留的 `VITE_API_BASE_URL` 不再生效（可直接删除）。
|
||
- **迁移动作**：`grep -n VITE_API_BASE_URL .env` 确认并删除该行。
|
||
|
||
### 3. `backups/` 纳入 `.gitignore`
|
||
|
||
- **变更**：`.gitignore` 新增 `backups/`。
|
||
- **原因**：`./scripts/deploy.sh backup` 会在仓库根产出 `backups/`（SQL + storage 归档），此前未被忽略，易被误提交（内含数据库全量数据）。
|
||
- **迁移动作**：无需操作；历史遗留的 `backup/`（旧目录）请自行确认是否已离线保存后删除。
|
||
|
||
### 4. `deploy.sh uninstall` 行为修正
|
||
|
||
- **变更**：`uninstall` 子命令改为 `docker compose down -v --rmi local --remove-orphans`，并修正提示文案。
|
||
- **原因**：旧实现里 `docker rmi $(docker images | grep nex-docus)` 是空操作（镜像名不带该前缀），且文案暗示会删除数据；实际 storage 采用宿主机 bind mount，`down -v` 不会删除文档文件。
|
||
- **影响**：卸载会删除命名卷（MySQL/Redis 数据）与本地构建镜像；`STORAGE_PATH` 指向的宿主机目录仍需手动删除。
|
||
- **迁移动作**：卸载前先执行 `./scripts/deploy.sh backup`。
|
||
|
||
### 5. 两套默认密码并存（重要，易踩坑）
|
||
|
||
| 场景 | 初始化管理员 | 新建普通用户默认密码 | 来源 |
|
||
| --- | --- | --- | --- |
|
||
| 本地开发（`scripts/start.sh` + `backend/scripts/init_db.py`） | `admin` / `admin@123` | `User@123` | `backend/scripts/init_db.py` 与 `config.py` 的默认值 |
|
||
| Docker 部署（`docker-compose.yml` + `backend/scripts/init_db.py`） | `admin` / `Admin@123456` | `User@123456` | `.env` 的 `ADMIN_PASSWORD` / `DEFAULT_USER_PASSWORD`（compose 注入，见本文第 8 条） |
|
||
|
||
- **原因**：历史原因两套初始化路径分别写死了不同默认值。
|
||
- **影响**：跨环境复现问题时会以为"密码错了"。
|
||
- **迁移动作**：**任何环境部署后立即修改管理员密码**；生产环境必须在 `.env` 显式设置 `ADMIN_PASSWORD`。
|
||
- 同时：`init_db.py` 的管理员默认邮箱由真实域名改为占位 `admin@example.com`（原为 `admin@unisspace.com`），部署后请在「个人设置」里改成实际邮箱。
|
||
|
||
### 6. 文档位置重组
|
||
|
||
- **变更**：根目录文档全部迁入 `docs/`。
|
||
|
||
| 旧位置 | 新位置 |
|
||
| --- | --- |
|
||
| `QUICKSTART.md` | `docs/quickstart.md` |
|
||
| `DATABASE.md` | `docs/database.md` |
|
||
| `DEPLOY.md` | `docs/deploy/README.md` |
|
||
| `CHANGELOG_DEPLOY.md` | `docs/deploy/changelog.md`（本文件） |
|
||
| `PROJECT.md` / `IMPLEMENTATION_PLAN.md` | `docs/archive/`（历史归档，与现状不符） |
|
||
| `docs/manual/docus系统使用手册.md` | `docs/manual/user-guide.md` |
|
||
| `DEPLOYEE.md` / `README_DOCKER.md` | 删除（内容与 `DEPLOY.md` 重复且过期） |
|
||
|
||
- **原因**：根目录 8 份 Markdown 重复/矛盾，且部分文档含明文生产凭据。
|
||
- **迁移动作**：外部书签按上表更新；文档总入口见 `docs/README.md`。
|
||
|
||
### 7. 后端版本号为 1.0.0
|
||
|
||
- **变更**：`backend/app/core/config.py` 的 `APP_VERSION` 从 `0.9.9` 改为 `1.0.0`，与前端 `package.json`、发布计划对齐。
|
||
- **影响**：`/openapi.json` 的 `info.version` 会随之变为 1.0.0；`/health` 无变化（`/health` 仅返回状态）；如运维脚本按版本号做灰度判断需重新对齐。
|
||
- **上线动作**：需执行 `git tag -a v1.0.0 -m "NEX Docus v1.0.0"`（见 [`docs/sdd/releases/v1.0.0.md`](../sdd/releases/v1.0.0.md)）。
|
||
|
||
### 8. `DEFAULT_USER_PASSWORD` 现在真的可以从 `.env` 配置
|
||
|
||
- **变更**：`docker-compose.yml` 的 backend 服务补上 `DEFAULT_USER_PASSWORD=${DEFAULT_USER_PASSWORD:-User@123456}`，`.env.example` 补上该键。
|
||
- **原因**：`config.py` 一直支持该配置项，但 compose 从未透传，Docker 部署下**改 `.env` 无效**，新建用户永远是 `User@123456`。
|
||
- **影响**：升级后在 `.env` 设置即可生效；未设置时行为不变。
|
||
- **迁移动作**：`echo 'DEFAULT_USER_PASSWORD=<随机值>' >> .env && docker compose up -d backend`。
|
||
|
||
### 9. 后端启动增加「安全自检」告警
|
||
|
||
- **变更**：`Settings.security_warnings()` 在应用启动时检查 `SECRET_KEY` 与 `DEFAULT_USER_PASSWORD`，命中仓库模板里的占位/默认值时打 `WARNING`（**只告警，不阻断启动**，避免影响存量部署）。
|
||
- **原因**：compose 用 `${SECRET_KEY:-your-secret-key-change-me-in-production}` 之类的兜底默认值，运维漏配 `.env` 时会带着**公开已知的 JWT 密钥**上线且毫无提示。
|
||
- **影响**：日志里可能出现 `[安全自检]` 开头的告警行；看到这行必须改配置，不要忽略。
|
||
- **迁移动作**：`SECRET_KEY=$(openssl rand -hex 32)` 写入 `.env`；`ADMIN_PASSWORD`、`DEFAULT_USER_PASSWORD` 改为随机值。
|
||
|
||
### 10. `.env.example` 去掉真实域名邮箱
|
||
|
||
- **变更**：`ADMIN_EMAIL` 从 `admin@unisspace.com` 改为占位 `admin@example.com`。
|
||
- **原因**：模板不应携带真实域名；compose 与 `init_db.py` 的默认值本就是 `admin@example.com`，两处不一致会让运维以为默认邮箱是前者。
|
||
- **迁移动作**：已有 `.env` 自行决定是否替换；部署后在「个人设置」里改成实际邮箱。
|
||
|
||
---
|
||
|
||
## v0.9.9 及更早（历史，仅作追溯）
|
||
|
||
> 以下条目来自旧 `CHANGELOG_DEPLOY.md`，其中提到的 `./deploy.sh` 现位于 `./scripts/deploy.sh`；早期版本号 `v1.0.1` 为文案占位，git 发布线此前最高仅到 v0.9.9。
|
||
|
||
### 前端端口 80 → 8080
|
||
- 避免与宿主机常见服务冲突；可用 `.env` 的 `FRONTEND_PORT` 覆盖。
|
||
|
||
### Storage 由 Docker Volume 改为宿主机 bind mount
|
||
- 新增 `STORAGE_PATH`（默认 `./storage`），便于直接访问、备份、挂载独立磁盘，数据独立于容器生命周期。
|
||
- 旧 volume 数据一次性导出：
|
||
```bash
|
||
docker run --rm -v nex-docus_storage_data:/from -v "$(pwd)/storage:/to" alpine \
|
||
sh -c "cd /from && cp -a . /to"
|
||
```
|
||
确认无误后再 `docker volume rm nex-docus_storage_data`。
|
||
|
||
### 后端容器时区固定为 Asia/Shanghai
|
||
- 容器内 `TZ=Asia/Shanghai`，避免日志与 `created_at` 与业务时间相差 8 小时。
|
||
|
||
### 新增 `/health` 健康检查
|
||
- 供 compose `healthcheck` 与外层负载均衡探活使用。
|
||
|
||
### Nginx 增加 SSE 支持
|
||
- 知识库对话为流式响应：`proxy_buffering off`、`proxy_read_timeout` 放大，避免答案被截断。
|