xiaoxia-saas/docs/全面代码审计报告-2026-06-21.md

# 全面代码审计报告 - 2026-06-21

## 一、审计目标

对小虾 SaaS 进行一次系统性代码审计，重点不是局部补丁，而是发现并修复：

- 架构分层不一致
- 重复入口和重复实现
- 安全与认证缺陷
- 外部依赖导入副作用
- 配置真源缺失
- 可验证的 P0/P1 Bug

## 二、本轮已确认并修复的问题

### 1. P0：简化认证使用 SHA256 存储密码

**涉及文件**：`apps/api/app/api/routes/auth_simple.py`

**问题**：
- 注册使用 `hashlib.sha256(password)` 保存密码。
- 登录用同样 SHA256 比对。
- 这是不可接受的密码存储方案，缺少 salt 和 cost factor。

**根因**：
- `auth_simple.py` 作为临时实现进入真实路由后没有回收。
- 项目已有 `PasswordHasher(bcrypt)`，但真实 API 没有复用。

**修复**：
- 注册改为 `password_hasher.hash_password()`。
- 登录改为 bcrypt 校验。
- 对历史 SHA256 用户做透明迁移：首次成功登录后自动升级为 bcrypt。
- 增加密码强度校验。

### 2. P0：登录返回不可验证随机 token

**涉及文件**：`apps/api/app/api/routes/auth_simple.py`、`apps/api/app/config.py`

**问题**：
- 登录返回 `secrets.token_urlsafe(32)`。
- Token 没有签名、没有 payload、没有过期时间、无法被标准认证中间件验证。

**根因**：
- 临时认证实现绕过了项目已有 JWT 设计。
- API settings 缺少 `JWT_SECRET_KEY` 配置项。

**修复**：
- 登录返回 HS256 JWT。
- JWT payload 包含 `sub/email/type/iat/exp`。
- 响应新增 `expires_in`。
- `Settings` 增加 `JWT_SECRET_KEY`，由 `.env` 可覆盖。

### 3. P1：API 路由包存在重复入口和导入副作用

**涉及文件**：`apps/api/app/api/routes/__init__.py`

**问题**：
- `routes/__init__.py` 维护了一份重复 `api_router`。
- 正式入口 `app/api/router.py` 也维护一份 `api_router`。
- 两者内容不一致，旧入口缺少后续生成/成片路由。
- 导入 `app.api.routes` 会连带导入所有路由和外部依赖。

**根因**：
- 迁移过程中保留了旧入口，没有明确唯一真源。

**修复**：
- `routes/__init__.py` 改为兼容转发，只导出 canonical `app.api.router` 中的 `api_router` 和 `health_router`。

### 4. P1：OSS SDK 为硬导入，导致无 OSS 本地环境无法导入 API Router

**涉及文件**：`apps/api/app/core/storage.py`

**问题**：
- `import oss2` 在模块顶层执行。
- 本地/测试环境未安装 `oss2` 时，导入任何包含 `generated_videos` 的 API router 都会失败。

**根因**：
- 外部存储适配器没有做到依赖可选和配置驱动。
- 无 OSS 配置时，本地 generated 文件已经可以工作，但代码仍强制要求 OSS SDK。

**修复**：
- `oss2` 改为可选导入。
- 只有配置了 OSS AK/SK 并实际创建 bucket 时才要求 `oss2`。
- 未配置 OSS 时，下载 URL 对本地 `/generated-files/` 直接返回，对 OSS URL 回退为公开 URL。
- 上传/下载等 OSS 专属操作在未配置时返回明确错误。

### 5. P1：API 配置存在双真源

**涉及文件**：`apps/api/app/config.py`、`apps/api/app/core/config.py`

**问题**：
- `app/config.py` 与 `app/core/config.py` 同时定义 Settings。
- 两套配置字段命名、OSS/MinIO、JWT、CORS 等含义不一致。
- 新代码主要使用 `app.config`，旧模块可能误导入 `app.core.config`。

**根因**：
- 早期目录重构后没有清理旧配置入口。

**修复**：
- 明确 `app.config` 为 API 配置唯一真源。
- `app/core/config.py` 改为兼容转发层，只 re-export canonical Settings/get_settings/settings。
- 避免未来继续在旧文件增加新字段导致漂移。

### 6. P1：旧认证/工作空间路由引用已移除的 DI Container

**涉及文件**：`apps/api/app/api/routes/auth.py`、`apps/api/app/api/routes/workspaces.py`、`apps/api/app/middleware/auth.py`

**问题**：
- 旧完整认证和 workspace 路由引用 `get_container()`。
- `apps/api/app/dependencies.py` 已无 `get_container()`。
- 当前 canonical router 未挂载它们，但任何误导入都会成为运行时炸弹。

**根因**：
- DI 重构后旧路由未删除也未迁移。
- “完整实现”文件名误导后续开发者可能重新挂载坏代码。

**修复**：
- 旧模块顶部显式标记为 legacy disabled。
- 误导入时立即抛出清晰错误，而不是深层 ImportError。
- 后续只能在重建 DI composition root 后重新启用。

### 7. P1：CI 质量门禁只打印版本，不执行检查

**涉及文件**：`.gitea/workflows/ci-cd.yml`、`.github/workflows/ci-cd.yml`

**问题**：
- CI 安装/验证工具版本后直接成功。
- `black/isort/flake8/bandit/pytest` 没有实际检查代码。
- develop/main 可能在红线问题未暴露时继续部署。

**根因**：
- 早期为了验证 CI 环境可用，留下了占位命令。
- 后续没有升级为真实质量门禁。

**修复**：
- CI 改为执行 `compileall`、`black --check`、`isort --check-only`、`flake8`、`bandit`。
- 测试步骤改为 `python -m pytest tests -q`。
- Gitea 与 GitHub workflow 保持一致，避免 CI 双轨漂移。

### 8. P1：Domain 层直接依赖 Redis/SMTP

**涉及文件**：`packages/domain/auth/session_store.py`、`packages/domain/auth/email_service.py`、`packages/adapters/redis/session_store.py`、`packages/adapters/smtp/email_service.py`

**问题**：
- Domain 层直接 import Redis、SMTP、email MIME 等基础设施实现。
- `packages.domain.auth.__init__` 导入时创建 Redis/SMTP 全局单例。
- Application use case 通过模块全局变量调用外部服务，测试只能 patch 全局变量。

**根因**：
- 基础设施实现被放进了 domain 包，破坏 Clean Architecture 依赖方向。
- 外部服务没有通过构造注入进入 use case。

**修复**：
- Redis session 实现迁移到 `packages/adapters/redis/session_store.py`。
- SMTP email 实现迁移到 `packages/adapters/smtp/email_service.py`。
- Domain 原路径保留兼容 shim，但不再导出全局外部服务单例。
- 注册、登录、登出、密码重置、邀请成员 use case 改为构造注入，默认使用 adapter 懒加载工厂。
- 相关测试从 patch 模块全局变量改为注入 mock 服务。

### 9. P1：API 路由层直接依赖具体 SQLAlchemy Adapter

**涉及文件**：`apps/api/app/api/routes/*.py`、`tests/unit/test_architecture_boundaries.py`

**问题**：
- 多个 API route 直接 import `SQLAlchemy*Repository`。
- 路由层本应只依赖 FastAPI dependency provider 和 application use case，不应知道具体仓储实现。
- 具体 adapter 只能出现在 composition root，例如 `apps/api/app/dependencies.py`。

**根因**：
- 为了类型标注方便，把基础设施类型泄漏进 API route。
- 没有架构守卫测试阻止回归。

**修复**：
- 移除 route 层对 `packages.adapters.sqlalchemy_impl` 的直接 import。
- route 层仓储参数改为 `Any`，具体实现保留在 `dependencies.py` 注入。
- 新增 `tests/unit/test_architecture_boundaries.py`，防止 route 层再次直接 import SQLAlchemy adapter。
- 同时守住 `domain.auth` 不再导出 Redis/SMTP 全局单例。

### 10. P1：Postgres psycopg Adapter 与 SQLAlchemy Adapter 双轨

**涉及文件**：`packages/adapters/postgres/*`、`tests/unit/test_architecture_boundaries.py`

**问题**：
- `packages/adapters/postgres/*` 与 `packages/adapters/sqlalchemy_impl/*` 同时存在。
- 主运行链路实际使用 SQLAlchemy，但旧 postgres package 仍可被新代码误导入。
- 双仓储会造成连接池、事务、模型字段、schema 迁移多头漂移。

**根因**：
- 历史 psycopg 实现被 SQLAlchemy 替代后没有明确废弃边界。
- 缺少测试禁止运行时代码继续引用旧 adapter。

**修复**：
- 删除 `packages/adapters/postgres/*` 旧 psycopg adapter 文件。
- 新增/强化架构守卫：`apps/`、`packages/`、`tests/` 不得 import `packages.adapters.postgres` 或 `Postgres*`。
- SQLAlchemy 明确为 SaaS 当前唯一主线持久化 adapter。

### 11. P1：部署入口双轨与根 Docker 文件漂移

**涉及文件**：`Dockerfile`、`docker-compose.yml`、`infra/docker/*`、`docs/DEPLOYMENT.md`

**问题**：
- 根 `Dockerfile` 与 `infra/docker/api.Dockerfile` 启动路径不同。
- 根 `docker-compose.yml` 与 `infra/docker/compose.yml` 拓扑不同。
- 实际 staging/CI 使用 `infra/docker`，但根入口仍可能被误用。

**根因**：
- 早期单 API 部署文件没有在多服务架构形成后废弃。
- 部署文档仍保留旧命令，容易引导错误操作。

**修复**：
- 根 `Dockerfile` 改为 deprecated sentinel，误 build 会失败并提示使用 `infra/docker/api.Dockerfile`。
- 根 `docker-compose.yml` 改为 deprecated sentinel，误 up 会失败并提示使用 `infra/docker/compose.yml`。
- `docs/DEPLOYMENT.md` 改为声明唯一部署入口和 Gitea Actions 部署约定。

### 12. P1：本地 CI 虚拟环境被误跟踪

**涉及文件**：`.gitignore`、`.venv-ci-root/`

**问题**：
- `.venv-ci-root` 中 3000+ 个第三方依赖文件被 Git 跟踪。
- 搜索、审计、CI 和 diff 都会被虚拟环境噪音污染。

**根因**：
- `.gitignore` 没有忽略 `.venv-ci-root/`。
- 本地 CI 工具环境被误加入索引。

**修复**：
- `.gitignore` 增加 `.venv-ci-root/`。
- 从 Git 索引移除 `.venv-ci-root`，本地文件保留。

### 13. P1：数据库 Schema 多真源漂移

**涉及文件**：`init-tables.sql`、`migrations/*.sql`、`packages/adapters/sqlalchemy_impl/models.py`、`docs/SCHEMA-MAINLINE.md`

**问题**：
- `init-tables.sql`、`migrations/*.sql`、SQLAlchemy models 曾同时定义表结构。
- 字段已经漂移，例如历史 SQL 使用 `assets.library_id/storage_key/mime_type`，当前 SQLAlchemy 使用 `assets.asset_library_id/file_url/file_type`。
- 旧运行时曾由 SQLAlchemy `Base.metadata.create_all()` 建表，部署缺少正式 migration 主线。

**根因**：
- Phase 迁移过程中 SQL 快照没有退役。
- Alembic 迁移链曾存在但 revision 已过期，和当前 SQLAlchemy model 不一致。

**修复**：
- `init-tables.sql` 改为 deprecated sentinel，误执行会直接失败。
- 新增并更新 `docs/SCHEMA-MAINLINE.md`，明确 SQLAlchemy models 是 schema 定义真源，Alembic 是迁移执行真源。
- 删除 stale Alembic revisions，新增 `alembic/versions/001_current_schema_baseline.py` 作为当前 schema baseline。
- `alembic/env.py` 改为从 `DATABASE_URL` 读取连接，并启用 `compare_type=True`。
- `infra/docker/deploy-staging.sh` 在服务启动前执行 `alembic upgrade head`；已有业务表但无版本表时执行 `alembic stamp head && alembic upgrade head`。
- API/Worker 默认关闭 `AUTO_CREATE_SCHEMA`，不再默认调用 `Base.metadata.create_all()`。
- staging 已验证：`alembic_version = 001`，health check healthy，`develop` 部署 job succeeded。
- 架构守卫禁止运行时代码引用 `init-tables.sql` 或历史 `migrations/001_initial_schema.sql`。

## 三、已补充测试

### 新增

- `tests/unit/test_auth_simple.py`
- `tests/unit/test_login_use_case.py`
- `tests/unit/test_register_user_use_case.py`
- `tests/unit/test_password_reset_use_case.py`
- `tests/unit/test_architecture_boundaries.py`

覆盖：
- 登录 token 是可验证 JWT。
- bcrypt 密码可登录。
- 历史 SHA256 密码登录后自动升级 bcrypt。
- 错误密码拒绝且不会写库。

### 已运行通过

```bash
python -m pytest tests/unit/test_architecture_boundaries.py tests/unit/test_auth_simple.py tests/unit/test_password_hasher.py tests/integration/test_generation_pipeline.py tests/integration/test_projects.py -q
python -m pytest tests/unit/test_login_use_case.py tests/unit/test_register_user_use_case.py tests/unit/test_password_reset_use_case.py tests/unit/test_invite_member_use_case.py tests/unit/test_session_store.py tests/unit/test_email_service.py -q
```

结果：`34 passed`，`52 passed`

## 四、仍需继续治理的问题

### P1：认证体系双轨（已收敛）

当前认证入口已收敛到 canonical route：

- `apps/api/app/api/routes/auth.py`
- `apps/api/app/auth.py`
- `packages/application/auth/*`
- `packages/adapters/sqlalchemy_impl/user_repository.py`

已完成：
- `auth.py` 不再是 disabled skeleton，也不依赖缺失的 `get_container()`。
- `api/router.py` 直接挂载 `app.api.routes.auth`。
- `auth_simple.py` 兼容 shim 已删除，认证入口只保留 `auth.py`。
- 登录/注册/当前用户均通过 `UserRepository + UseCase + app.auth`，route 层不再承载认证业务逻辑。

剩余建议：
1. 持续用 grep/架构测试防止 `auth_simple.py` 路径回流。
2. 根据产品需要补齐 password reset / verify email 的正式 route。
3. 接入真实邮件 adapter 前继续保持 no-op email delivery。

### P1：认证扩展路由缺失（已补齐）

已完成：
- `GET /api/v1/auth/verify-email?token=...`
- `POST /api/v1/auth/verify-email`
- `POST /api/v1/auth/password/forgot`
- `POST /api/v1/auth/forgot-password`
- `POST /api/v1/auth/password/reset`
- `POST /api/v1/auth/reset-password`

说明：
- 同时保留后端历史路径和前端现有路径，避免前后端命名漂移导致功能不可用。
- 路由仍通过 `UserRepository + UseCase`，不在 route 层写业务逻辑。
- 邮件发送在当前 compatibility route 中仍使用 no-op email service，接入真实 SMTP adapter 前不会对外发信。
- 已修复 password reset token 过期判断中的 naive/aware datetime 比较风险。

### P1：外部服务 adapter 化收尾（已配置驱动）

已完成：
- 认证 route 不再持有私有 no-op email/session 类，改为从 `apps/api/app/dependencies.py` 获取配置驱动 adapter。
- `ENABLE_EMAIL_DELIVERY=false` 时使用 no-op email service，`true` 时按 SMTP 配置创建 `EmailService`。
- `ENABLE_REDIS_SESSIONS=false` 时使用 no-op session store，`true` 时按 `REDIS_URL` 创建 Redis session store。
- SMTP/Redis no-op 实现放在 adapter 层，use case 仍通过构造注入使用。

剩余建议：
- Production 开启前需要真实 SMTP/Redis 连接验证和密钥审计。

### P1：Domain 层存在外部基础设施依赖

涉及：
- `packages/domain/auth/session_store.py` 直接依赖 Redis。
- `packages/domain/auth/email_service.py` 直接依赖 SMTP。

问题：
- 违反 Clean Architecture。
- Domain import 会创建全局外部服务实例。
- 错误处理使用 `print` 和吞异常。

建议：
- 抽象 `SessionStore`、`EmailSender` port。
- Redis/SMTP 实现迁移到 adapters。
- UseCase 通过构造函数注入 port。

### P1：Repository 体系双轨（已收敛）

当前持久化主线：

- `packages/adapters/sqlalchemy_impl/*`

已完成：
- 旧 `packages/adapters/postgres/*` psycopg adapter 已删除。
- 架构守卫禁止运行时代码重新引用 `packages.adapters.postgres` 或 `Postgres*`。
- Workspace/User/Member/Invitation 已走 SQLAlchemy adapter 与 API composition root。

剩余建议：
- 继续检查文档和脚本中的旧术语，避免恢复 psycopg adapter。

### P1：存储命名漂移（已收敛）

已完成：
- 运行时代码改用 `OSSStorageService` / `get_storage_service` 命名。
- `apps/api/app/core/storage.py` 仅保留 `MinIOService` / `get_minio_service` 兼容别名作为边界层。
- 架构守卫禁止 runtime/test 代码继续引用 MinIO 命名。
- 当前主线为 OSS；未配置 OSS 时，生成文件通过本地 `/generated-files/` fallback 公开访问。

### P2：Bandit 安全告警（已清零）

已完成：
- B104：API bind 地址改为配置驱动，容器内 `0.0.0.0` 明确标注为 bind address，外部暴露由 Docker/Nginx 控制。
- B104：登录默认 `ip_address` 从 `0.0.0.0` 改为 `unknown`，避免把未知 IP 伪装成 bind-all 地址。
- B110：worker 失败状态更新不再吞异常；返回 `state_error` 并执行 rollback。
- B404/B603/B607：FFmpeg/FFprobe 通过固定参数列表、`shell=False`、`shutil.which` 解析路径，并用 `nosec` 标注剩余可接受风险。
- 当前 `python -m bandit -r apps packages -q` 通过。

### P2：临时代码仍在主线

发现：
- `auth_simple.py` shim 已删除。
- 部分测试和文档仍引用旧 MinIO/OSS 混合术语。
- `__pycache__` 文件出现在工作树扫描中，需确认 `.gitignore` 和仓库状态。

### P1：生产 Alembic 准备（已形成 checklist）

已完成：
- 新增 `docs/PRODUCTION-RELEASE-CHECKLIST.md`。
- 明确生产发布前必须执行：staging 验证、CI 验证、生产 env 审计、数据库备份、Alembic 状态判断、发布后 smoke。
- 明确首次生产接入 Alembic 的判断规则：已有 `alembic_version` 则 upgrade；有业务表但无版本表则 stamp head 后 upgrade；空库直接 upgrade。
- 明确回滚策略：应用优先回滚 tag；数据库只在验证过 downgrade 时使用 downgrade，否则以备份恢复作为最终兜底。

剩余建议：
- 真正生产发布前，基于当时生产容器名和 DB 名写一次性恢复 runbook。

## 五、下一步建议修复顺序

1. Production 外部服务上线：验证 SMTP/Redis 连接、密钥和告警。
2. 验证真实 SMTP/Redis/OSS 凭证并完成生产外部服务 smoke。
3. 全量测试和 CI：后端 unit/integration + 前端 type-check/build + staging smoke。