开始之前

第一章　开始之前

说明

先理解最终架构、版本特征与部署前准备。

#1. 最终版架构

公开访问
https://你的域名/
        ↓
浏览器本地生成 TOTP
Secret 不上传服务器

管理员后台
https://你的域名/admin
        ↓
SQLite
        ↓
TOTP Secret 使用 XChaCha20-Poly1305 加密
        ↓
vault.key 位于 Web Root 外

备份
SQLite + vault.key + config + manifest
        ↓
tar.gz
        ↓
AGE Public Key 加密
        ↓
.tar.gz.age
        ↓
Microsoft 365 OneDrive
TOTP-Vault-Backup/Backups

最终 OneDrive 身份验证方式：

OAuth 2.0 Authorization Code Flow
Delegated Files.ReadWrite
offline_access
Refresh Token

最终版：

不需要 Drive ID
不使用 client_credentials
不使用 Files.ReadWrite.AppFolder Application permission
不使用 /special/approot

#2. 最终发布包已合并的修复

最终代码已经合并：

TOTP-Vault-v1.0.0-Baota
+
TOTP-Vault-OneDrive-Delegated-Hotfix-20260824
+
TOTP-Vault-OneDrive-Fixed-Folder-Hotfix-20260824
+
实际部署过程中确认的最终修复

最终额外修复：

1. Ubuntu apt 安装 AGE 后自动识别 /usr/bin/age
2. proc_open 在安装阶段直接检查
3. Composer 遇到 putenv 被禁用时自动跳过，不再中断安装
4. /www/server/totp-vault 父目录权限自动修复
5. 安装中断后可以安全重新运行 install.sh
6. 已存在管理员时不会再次创建
7. shell_exec 被禁用时 artisan 不再直接 Fatal Error
8. HEAD 请求按 GET 路由处理，curl -I 不再产生假 404
9. OAuth Session SameSite 改为 Lax
10. CSP 放行 https://login.microsoftonline.com OAuth 跳转
11. OneDrive 使用 Delegated Files.ReadWrite + Refresh Token
12. OneDrive 固定只操作 TOTP-Vault-Backup/Backups
13. Health Check 增加 proc_open 检查
14. 新增 tools/offline-export.php，可在网站完全不可用时离线导出全部 TOTP Secret

#3. 新服务器部署前准备

准备：

Ubuntu 22.04 服务器
服务器公网 IPv4
一个域名或子域名
SSH 登录权限
Microsoft 365 企业账号
Microsoft Entra App Registration 管理权限
Windows 电脑，用于离线保存 AGE Private Key

本文示例：

域名：2fa.example.com
项目：/www/wwwroot/2fa.example.com
PHP：8.2
PHP CLI：/www/server/php/82/bin/php
PHP-FPM socket：/tmp/php-cgi-82.sock
PHP-FPM 用户：www

把 2fa.example.com 换成你自己的域名。

下一章服务器初始化 →