mula
/
nex_docus
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
nex_docus/docs/deploy/changelog.md

8.3 KiB
Raw Blame History

部署与配置变更日志

记录影响部署方式、配置项、运维命令的变更。纯功能/界面变更记录见 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。

  • 迁移动作：

    ./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）。

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 数据一次性导出： 
    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 放大，避免答案被截断。