docs下为 项目大纲、执行计划，由Gemini生成
task_progress.md 是AI的任务执行记录，使用cursor和claude-4-sonnet生成
以下介绍同样使用ai生成
- 端到端加密: 所有2FA密钥使用用户主密码通过AES-256-GCM加密存储
- 密钥派生: 使用PBKDF2算法（100,000次迭代）从主密码派生加密密钥
- 零知识架构: 服务器不保存主密码，采用Canary账户机制验证密码正确性
- 会话管理: 安全的HTTP-Only Cookie会话管理
- HTTPS强制: 生产环境强制使用HTTPS通信
- 技术栈: Python + FastAPI + SQLite + Tailwind CSS
- 资源占用: 极低的服务器资源消耗
- 快速启动: 从零到运行仅需几分钟
- 依赖精简: 最小化的依赖包，减少安全风险
- 响应式设计: 支持桌面和移动设备
- 美观UI: 基于Tailwind CSS的现代化界面
- 实时更新: TOTP代码实时生成和倒计时
- 直观操作: 简洁直观的用户体验
- 账户管理: 支持添加、编辑、删除2FA账户
- 分组管理: 账户可按分组组织，支持自定义排序
- 多种添加方式: 支持手动输入密钥或扫描二维码
- 标准兼容: 完全兼容Google Authenticator、Authy等标准
- Docker支持: 一键Docker Compose部署
- 自动HTTPS: 集成Caddy自动获取SSL证书
- 配置简单: 最小化配置即可运行
- 数据持久化: SQLite数据库文件持久化存储
- Web框架: FastAPI 0.115+ （高性能、自动API文档）
- ASGI服务器: Uvicorn （FastAPI官方推荐）
- 数据库: SQLite （轻量级、零配置）
- ORM: SQLAlchemy 2.0+ （现代化数据库操作）
- 加密库: cryptography （PBKDF2 + AES-256-GCM）
- TOTP: PyOTP （标准TOTP实现）
- 样式框架: Tailwind CSS （按需生成、极小体积）
- 交互逻辑: Vanilla JavaScript / Alpine.js
- 二维码扫描: html5-qrcode （浏览器内二维码识别）
- 模板引擎: Jinja2 （服务端渲染）
- 容器化: Docker + Docker Compose
- 反向代理: Caddy （自动HTTPS、极简配置）
- 数据持久化: Docker Volume （数据库文件持久化）
- 操作系统: Linux、macOS、Windows
- Python: 3.12+
- 内存: 512MB RAM
- 存储: 100MB 可用空间
- 网络: HTTP/HTTPS访问
- CPU: 1 vCPU
- 内存: 1GB RAM
- 存储: 1GB 可用空间
- 域名: 用于HTTPS自动证书（可选）
- 克隆项目
git clone https://github.com/huanghq996/AuthNest.git
cd authnest- 启动服务
docker-compose up -d- 访问应用
- 本地访问: http://localhost
- 生产环境: 配置域名后自动获取HTTPS证书
- 环境准备
# 创建虚拟环境
python -m venv .venv
# 激活虚拟环境
# Windows
.venv\Scripts\activate
# Linux/macOS
source .venv/bin/activate
# 安装依赖
pip install -r requirements.txt- 启动应用
uvicorn app.main:app --host 0.0.0.0 --port 8000- 访问应用
-
设置主密码
- 首次访问时，系统会要求设置主密码
- 请妥善保管主密码，丢失将无法访问数据
-
创建分组
- 点击"添加分组"创建账户分组
- 例如：工作、个人、银行等
-
添加账户
- 点击"添加账户"按钮
- 选择所属分组
- 输入颁发者（如Google、GitHub）
- 输入标签（如邮箱地址）
- 添加密钥方式：
- 手动输入: 输入Base32格式的密钥
- 扫描二维码: 使用摄像头扫描QR码
-
查看TOTP代码
- 登录后在仪表盘查看所有账户的6位数验证码
- 代码每30秒自动更新
- 进度条显示剩余有效时间
-
管理账户
- 编辑账户信息（颁发者、标签、分组）
- 删除不需要的账户
- 拖拽排序（功能开发中）
-
管理分组
- 重命名分组
- 删除空分组
- 调整分组顺序
-
主密码安全
- 使用强密码（至少12位，包含大小写字母、数字、特殊字符）
- 定期更换主密码
- 不要与其他账户使用相同密码
-
数据备份
- 定期备份
data/app.db数据库文件 - 记录重要账户的备用恢复代码
- 考虑使用多种2FA工具避免单点故障
- 定期备份
-
访问安全
- 生产环境务必使用HTTPS
- 设置强密码保护服务器
- 考虑使用VPN等额外访问控制
创建.env文件进行配置：
# 应用配置
DEBUG=False
SECRET_KEY=your-super-secret-key-change-me
# 数据库配置
DATABASE_URL=sqlite:///./data/app.db
# 服务器配置
HOST=0.0.0.0
PORT=8000
# HTTPS配置（生产环境）
HTTPS_ONLY=True
ALLOWED_HOSTS=yourdomain.com,*.yourdomain.com默认的docker-compose.yml配置：
version: '3.8'
services:
app:
build: .
volumes:
- ./data:/app/data
environment:
- SECRET_KEY=your-super-secret-key-change-me
caddy:
image: caddy:2-alpine
ports:
- "80:80"
- "443:443"
volumes:
- ./Caddyfile:/etc/caddy/Caddyfile
- caddy_data:/data
- caddy_config:/config
depends_on:
- app
volumes:
caddy_data:
caddy_config:生产环境Caddyfile示例：
yourdomain.com {
reverse_proxy app:8000
encode gzip
# 安全头
header {
X-Content-Type-Options nosniff
X-Frame-Options DENY
X-XSS-Protection "1; mode=block"
Strict-Transport-Security "max-age=31536000; includeSubDomains"
}
}authnest/
├── app/ # 应用代码
│ ├── api/ # API路由
│ │ ├── __init__.py
│ │ ├── auth.py # 认证相关API
│ │ ├── accounts.py # 账户管理API
│ │ ├── groups.py # 分组管理API
│ │ ├── dependencies.py # 依赖注入
│ │ └── schemas.py # 数据模型
│ ├── core/ # 核心逻辑
│ │ ├── __init__.py
│ │ ├── security.py # 加密解密
│ │ ├── totp.py # TOTP生成
│ │ └── config.py # 配置管理
│ ├── db/ # 数据库相关
│ │ ├── __init__.py
│ │ ├── models.py # SQLAlchemy模型
│ │ ├── database.py # 数据库连接
│ │ └── crud.py # 数据库操作
│ ├── static/ # 静态文件
│ │ ├── css/
│ │ │ └── style.css # Tailwind生成的CSS
│ │ └── js/
│ │ └── app.js # 前端JavaScript
│ ├── templates/ # HTML模板
│ │ ├── base.html # 基础模板
│ │ ├── login.html # 登录页面
│ │ └── dashboard.html # 仪表盘页面
│ └── main.py # 应用入口
├── data/ # 数据目录（运行时生成）
│ └── app.db # SQLite数据库
├── docs/ # 项目文档
├── docker-compose.yml # Docker编排
├── Dockerfile # Docker镜像构建
├── Caddyfile # 反向代理配置
├── requirements.txt # Python依赖
├── tailwind.config.js # Tailwind配置
└── README.md # 项目说明
- 环境搭建
# 克隆项目
git clone https://github.com/huanghq996/AuthNest.git
cd authnest
# 创建虚拟环境
python -m venv .venv
source .venv/bin/activate # Linux/macOS
# .venv\Scripts\activate # Windows
# 安装依赖
pip install -r requirements.txt- 运行开发服务器
uvicorn app.main:app --reload --host 127.0.0.1 --port 8000- 访问开发环境
- 应用地址: http://127.0.0.1:8000
- API文档: http://127.0.0.1:8000/docs
- 交互式文档: http://127.0.0.1:8000/redoc
- Python: 遵循PEP 8规范
- 类型注解: 使用Python类型提示
- 文档字符串: 使用Google风格的docstring
- 代码格式化: 使用black格式化代码
- 导入排序: 使用isort排序导入
# 运行单元测试
pytest tests/
# 代码覆盖率
pytest --cov=app tests/
# 代码质量检查
flake8 app/
mypy app/- 密钥派生
# 用户输入主密码 -> PBKDF2(100,000次迭代) -> 256位加密密钥
key = PBKDF2HMAC(
algorithm=hashes.SHA256(),
length=32,
salt=salt,
iterations=100000,
backend=default_backend()
).derive(password.encode())- 数据加密
# AES-256-GCM加密
aesgcm = AESGCM(key)
ciphertext = aesgcm.encrypt(nonce, plaintext, None)
# 存储格式: salt(16字节) + nonce(12字节) + ciphertext- 密码验证
# 使用Canary账户验证密码正确性
canary_data = "AuthNest OK"
encrypted_canary = encrypt(canary_data, master_password)
# 验证时尝试解密，成功则密码正确- 零知识: 服务器不知道用户的主密码
- 前向安全: 即使服务器被攻破，历史数据依然安全
- 认证加密: AES-GCM提供机密性和完整性保护
- 盐值随机: 每个密钥使用唯一随机盐值
- 会话安全: HTTP-Only Cookie，防止XSS攻击
- 购买域名并配置DNS
A记录: yourdomain.com -> 服务器IP
A记录: *.yourdomain.com -> 服务器IP (可选，支持子域名)
- 更新Caddyfile
yourdomain.com {
reverse_proxy app:8000
}- 启动服务
docker-compose up -dCaddy会自动获取Let's Encrypt SSL证书。
- 服务器安全
# 更新系统
sudo apt update && sudo apt upgrade -y
# 配置防火墙
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
# 禁用密码登录，使用密钥认证
sudo vim /etc/ssh/sshd_config- 容器安全
# 使用非root用户运行容器
# 限制容器资源使用
# 定期更新镜像- 数据备份
# 定期备份数据库
cp data/app.db backup/app.db.$(date +%Y%m%d_%H%M%S)
# 自动备份脚本
#!/bin/bash
BACKUP_DIR="/path/to/backup"
DATE=$(date +%Y%m%d_%H%M%S)
cp data/app.db "$BACKUP_DIR/app.db.$DATE"
find "$BACKUP_DIR" -name "app.db.*" -mtime +30 -delete- 日志配置
# docker-compose.yml
services:
app:
logging:
driver: "json-file"
options:
max-size: "10m"
max-file: "3"- 健康检查
# 检查服务状态
curl -f http://localhost/api/health || exit 1- 性能监控
# 监控容器资源使用
docker stats authnest_app_1
# 监控磁盘空间
df -h# 检查Python版本
python --version # 需要3.12+
# 检查依赖
pip install -r requirements.txt
# 检查数据目录权限
chmod 755 data/# 删除旧数据库
rm data/app.db
# 重新启动应用自动初始化
uvicorn app.main:app --reload# 清理Docker缓存
docker system prune -f
# 重新构建
docker-compose build --no-cache# 检查域名解析
nslookup yourdomain.com
# 检查防火墙
sudo ufw status
# 查看Caddy日志
docker-compose logs caddy- 应用日志
# 查看应用日志
docker-compose logs app
# 实时跟踪日志
docker-compose logs -f app- Caddy日志
# 查看Caddy日志
docker-compose logs caddy
# 查看访问日志
docker exec -it authnest_caddy_1 cat /var/log/caddy/access.log- 系统日志
# 查看系统日志
journalctl -u docker
# 查看内存使用
free -h
# 查看磁盘使用
df -h-
Fork项目
- 点击GitHub页面右上角的Fork按钮
-
创建分支
git checkout -b feature/new-feature- 提交更改
git add .
git commit -m "Add new feature"- 推送分支
git push origin feature/new-feature- 创建Pull Request
- 在GitHub上创建Pull Request
- 详细描述更改内容
-
代码质量
- 遵循PEP 8代码规范
- 添加类型注解
- 编写单元测试
- 更新文档
-
提交信息
- 使用清晰的提交信息
- 格式：
type: description - 类型：feat, fix, docs, style, refactor, test
-
测试要求
- 新功能必须包含测试
- 确保所有测试通过
- 代码覆盖率 > 80%
-
Bug报告
- 使用GitHub Issues
- 提供详细的重现步骤
- 包含错误日志
- 说明环境信息
-
功能请求
- 详细描述需求
- 说明使用场景
- 提供设计建议
本项目采用 MIT许可证。
MIT License
Copyright (c) 2024 AuthNest
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
感谢以下开源项目和贡献者：
- FastAPI - 现代化的Python Web框架
- SQLAlchemy - Python SQL工具包和ORM
- Starlette - 轻量级ASGI框架
- Tailwind CSS - 实用优先的CSS框架
- PyOTP - Python TOTP/HOTP库
- Cryptography - Python加密库
- Caddy - 自动HTTPS的Web服务器
- Docker - 容器化平台
特别感谢所有贡献代码、报告问题和提出建议的开发者！
- 拖拽排序功能
- 账户导入/导出
- 多语言支持
- 暗色主题
- 移动端PWA支持
- 备份和恢复功能
- 批量操作
- 搜索和过滤
- 使用统计
- API密钥管理
- 多用户支持
- 团队协作功能
- 审计日志
- 集成外部认证
- 插件系统
如果这个项目对你有帮助，请给我们一个⭐️！
让我们一起构建更安全的数字世界！ 🔐