dmitriyVasilievich1986/keychain

[](https://github.com/dmitriyVasilievich1986/keychain/actions/workflows/build_backend.yml) [](https://github.com/dmitriyVasilievich1986/keychain/actions/workflows/build_frontend.yml) # Keychain 一个现代化、安全、具备端到端加密的自托管密码管理解决方案。 ## 概述 Keychain 是一个全栈密码管理器，提供了一种安全的方式来存储、管理和访问您的密码。它使用现代 Web 技术构建，具有基于 React 的前端、带有加密存储的 FastAPI 后端，并设计为可通过 Docker 轻松进行自托管。 ### 核心功能 - **安全存储**：所有敏感字段值均使用 Fernet 对称加密进行加密 - **JWT 身份验证**：具有可配置过期时间的基于 token 的身份验证 - **自托管**：通过 Docker 部署，完全控制您的数据 - **现代化 UI**：简洁且响应式的 Material-UI 界面 - **RESTful API**：为所有操作提供文档完善的 API - **CLI 工具**：提供全面的命令行管理界面 - **数据库迁移**：使用 Alembic 进行版本控制的 schema 管理 - **类型安全**：全面采用 TypeScript 前端和 Python type hints ## 架构 该应用程序由通过 Docker Compose 编排的三个主要组件组成： ``` ┌─────────────┐ │ Browser │ └──────┬──────┘ │ HTTP (Port 80) ↓ ┌─────────────────────────────────────────┐ │ Nginx (Reverse Proxy) │ │ • Serves static frontend assets │ │ • Proxies /api/* to backend │ │ • Handles gzip compression │ │ • Manages cache headers │ └────────┬────────────────────┬───────────┘ │ │ │ Static Files │ API Calls ↓ ↓ ┌──────────────┐ ┌──────────────────┐ │ Frontend │ │ Backend │ │ │ │ │ │ React 19 │ │ FastAPI │ │ TypeScript │ │ Python 3.13 │ │ MUI │ │ SQLAlchemy │ │ Zustand │ │ Cryptography │ └──────────────┘ └────────┬─────────┘ │ ↓ ┌──────────────┐ │ SQLite DB │ │ (Encrypted) │ └──────────────┘ ``` ## 项目结构 ``` keychain/ ├── backend/ # Python FastAPI backend │ ├── src/keychain/ # Source code │ │ ├── config/ # Configuration management │ │ ├── modules/ # FastAPI app and routes │ │ ├── services/ # Business logic services │ │ └── utils/ # CLI and utilities │ ├── configurations/ # YAML config files │ ├── Dockerfile # Multi-stage Docker build │ ├── pyproject.toml # Python dependencies │ └── README.md # Backend documentation ├── frontend/ # React TypeScript frontend │ ├── src/ # Source code │ │ ├── components/ # Reusable UI components │ │ ├── pages/ # Page components │ │ ├── store/ # Zustand state management │ │ └── utils/ # Utilities and API client │ ├── package.json # Node dependencies │ ├── vite.config.ts # Vite configuration │ └── README.md # Frontend documentation ├── nginx/ # Nginx configuration │ └── nginx.conf # Reverse proxy config ├── static/ # Static assets and build output │ ├── assets/ # Frontend build artifacts │ └── i/ # Images ├── docker-compose.local.yaml # Docker Compose configuration ├── .github/workflows/ # CI/CD pipelines └── README.md # This file ``` ## 技术栈 ### 后端 - Python 3.13 - FastAPI - Web 框架 - SQLAlchemy - ORM - Alembic - 数据库迁移 - Pydantic - 数据验证 - PyJWT - 身份验证 - Cryptography (Fernet) - 加密 - Uvicorn - ASGI 服务器 ### 前端 - React 19 - TypeScript - Vite - 构建工具 - Material-UI (MUI) - 组件库 - Zustand - 状态管理 - React Router - 路由 - Axios - HTTP 客户端 - Sass - 样式 ### 基础设施 - Docker & Docker Compose - Nginx - 反向代理 - SQLite - 数据库 ## 使用 Docker Compose 快速开始 ### 前置条件 - 已安装 Docker 和 Docker Compose - Git ### 1. 克隆仓库 ``` git clone https://github.com/dmitriyVasilievich1986/keychain.git cd keychain ``` ### 2. 配置后端 在 `backend/` 目录下创建 `.env` 文件： ``` cd backend ``` 创建 `backend/.env`： ``` CONFIG_FILE_PATH=/opt/backend/configurations/local.yaml CRYPTOGRAPHY__SECRET_KEY= AUTH__JWT_SECRET_KEY= ``` 生成加密密钥（需要 Python 3.13）： ``` # 在本地安装依赖以生成密钥 python -m venv .venv source .venv/bin/activate pip install cryptography pyjwt # 生成 Fernet 密钥 python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())" # 生成 JWT 密钥 python -c "import secrets; print(secrets.token_urlsafe(32))" ``` ### 3. 启动应用程序 在根目录下执行： ``` # 仅启动后端和 nginx（推荐用于生产环境） docker-compose -f docker-compose.local.yaml up -d # 或者在开发模式中包含前端 docker-compose -f docker-compose.local.yaml --profile frontend up -d ``` ### 4. 初始化数据库 ``` # 访问后端容器 docker exec -it keychain-backend bash # 运行迁移 keychain db upgrade # 创建首个用户 keychain db-client user create --username admin --email admin@example.com --password yourpassword # 退出容器 exit ``` ### 5. 构建前端（如果未使用 frontend profile） ``` cd frontend npm install npm run build # Outputs to ../static/ ``` ### 6. 访问应用程序 打开浏览器并访问： ``` http://localhost ``` 应用程序现已运行，配置如下： - 前端：由 Nginx 在端口 80 上提供服务 - 后端 API：`http://localhost/api/` - 后端直接访问：`http://localhost:8000`（如有需要） ## Docker Compose 配置 `docker-compose.local.yaml` 文件编排了三个服务： ### 服务 #### 1. Nginx (keychain-nginx) ``` ports: 80:80 ``` - **用途**：用作反向代理和静态文件服务器 - **配置**：`nginx/nginx.conf` - **职责**： - 从 `/static/` 路径提供 React 前端服务 - 将 API 请求（`/api/*`）代理到后端服务 - 处理 gzip 压缩以提升性能 - 为静态资源设置缓存头（图片和 JS bundle 为期 1 年） - 使用 `try_files` 回退到 `index.html` 以实现 SPA 路由 - **卷（Volumes）**： - `./nginx/nginx.conf` → 配置文件 - `./static/` → 前端构建输出和静态资源 #### 2. 后端 (keychain-backend) ``` ports: 8000:8000 ``` - **用途**：FastAPI 应用程序服务器 - **构建**：使用来自 `./backend` 的多阶段 Dockerfile - **环境**： - 加载 `.env` 文件以获取密钥 - `CONFIG_FILE_PATH`：指向 YAML 配置文件 - **卷（Volumes）**（用于开发）： - `./backend/configurations/` → 配置文件 - `./backend/src/` → 源代码（用于热重载） - `./backend/keychain.sqlite` → 数据库持久化 - **健康检查**：每 60 秒轮询一次 `/health` endpoint - **依赖**：无（最先启动） #### 3. 前端 (keychain-frontend) ``` profile: frontend ``` - **用途**：开发构建服务器（可选） - **Profile**：仅在使用 `--profile frontend` 明确请求时启动 - **镜像**：Node.js 24 - **环境**： - `VITE_API_HOST`：API endpoint（留空 = 相对 URL） - `VITE_IMAGES_HOST`：图片路径前缀 - **命令**：运行 `scripts/start.sh`，该脚本会安装依赖并启动 Vite 开发服务器 - **卷**：挂载源文件和配置以进行热重载 - **注意**：在生产环境中，请在本地构建前端并通过 Nginx 提供服务 ### 使用模式 **开发环境**（支持热重载）： ``` docker-compose -f docker-compose.local.yaml --profile frontend up ``` **生产环境**（预构建的前端）： ``` # 首先构建前端 cd frontend && npm run build && cd .. # 启动后端和 nginx docker-compose -f docker-compose.local.yaml up -d ``` **重新构建后端**： ``` docker-compose -f docker-compose.local.yaml build backend docker-compose -f docker-compose.local.yaml up -d ``` ## 开发环境配置 ### 后端开发 有关详细的后端配置说明，请参阅 [backend/README.md](./backend/README.md)。 快速开始： ``` cd backend python -m venv .venv source .venv/bin/activate pip install -e . keychain db upgrade keychain run --reload ``` ### 前端开发 有关详细的前端配置说明，请参阅 [frontend/README.md](./frontend/README.md)。 快速开始： ``` cd frontend npm install npm run dev ``` ## CLI 命令 后端包含一个用于管理的综合 CLI： ``` # 应用程序 keychain version # Show version keychain run # Start server keychain show-config # Display configuration # 数据库管理 keychain db upgrade # Run migrations keychain db current # Show current version keychain db revision -m "message" # Create migration # 用户管理 keychain db-client user create --username admin --email admin@example.com --password secret keychain db-client user list keychain db-client user get --user-id 1 # 密码管理 keychain db-client password create --name "Gmail" --user-id 1 keychain db-client password list --user-id 1 # 字段管理 keychain db-client field create --name "username" --value "user@example.com" --password-id 1 keychain db-client field list --password-id 1 # 安全 keychain cryptography generate-key # Generate encryption key keychain cryptography encrypt TEXT # Encrypt data keychain cryptography decrypt TOKEN # Decrypt data keychain access-token generate-key # Generate JWT secret keychain access-token generate 1 # Generate token for user ID ``` ## API 文档 后端运行后，可在以下地址获取交互式 API 文档： - **Swagger UI**：`http://localhost:8000/docs` - **ReDoc**：`http://localhost:8000/redoc` ### 主要 Endpoint - `POST /api/v1/login` - 用户身份验证 - `GET /api/v1/user` - 获取当前用户 - `GET /api/v1/password` - 密码列表 - `POST /api/v1/password` - 创建密码 - `GET /api/v1/password/{id}` - 获取密码及其解密后的字段 - `POST /api/v1/field` - 创建加密字段 - `GET /health` - 健康检查 - `GET /version` - 版本信息 ## 环境变量 ### 后端 ``` CONFIG_FILE_PATH # Path to YAML config CRYPTOGRAPHY__SECRET_KEY # Fernet encryption key AUTH__JWT_SECRET_KEY # JWT signing secret DB__DB_URI # Database connection string AUTH__ACCESS_TOKEN_EXPIRE_MINUTES # Token expiration (default: 30) INFO__DEBUG # Debug mode (true/false) ``` ### 前端 ``` VITE_API_HOST # API base URL (empty for relative) VITE_IMAGES_HOST # Image path prefix ``` ## 安全注意事项 - **加密**：所有敏感字段值在静态存储时均使用 Fernet (AES-128) 加密 - **身份验证**：具有可配置过期时间的 JWT token - **密码哈希**：用户密码使用 Werkzeug 的安全方法进行哈希处理 - **HTTPS**：在生产环境中使用反向代理（如带有 Let's Encrypt 的 Nginx） - **密钥管理**：切勿将 `.env` 文件或密钥提交到版本控制系统中 - **数据库**：定期备份 SQLite 数据库 - **更新**：及时更新依赖项以获取安全补丁 ## 生产环境部署 ### 建议 1. **使用 HTTPS**：配置 SSL/TLS 证书（Let's Encrypt） 2. **外部数据库**：在生产环境中考虑使用 PostgreSQL 替代 SQLite 3. **密钥管理**：使用安全的密钥管理解决方案 4. **监控**：实施健康检查和监控 5. **备份**：定期进行自动化的数据库备份 6. **资源限制**：在生产环境中设置容器资源限制 7. **日志记录**：配置集中式日志记录 ### 生产环境 nginx 配置示例 ``` server { listen 443 ssl http2; server_name yourdomain.com; ssl_certificate /path/to/cert.pem; ssl_certificate_key /path/to/key.pem; # Include the rest of nginx.conf... } ``` ## 故障排除 ### 后端无法启动 - 检查 `.env` 文件是否存在且包含有效的密钥 - 验证数据库迁移是否为最新：`docker exec keychain-backend keychain db current` - 检查日志：`docker logs keychain-backend` ### 前端构建失败 - 确保已安装 Node.js 18+ - 清除 node_modules 并重新安装：`rm -rf node_modules && npm install` - 检查 TypeScript 错误：`npm run build` ### API 调用失败 - 验证后端是否正在运行：`curl http://localhost:8000/health` - 检查 nginx 配置是否正确代理了 `/api/` 请求 - 检查浏览器网络选项卡，查看是否存在 CORS 或 404 错误 ### 数据库错误 - 确保已应用迁移：`keychain db upgrade` - 检查数据库文件权限 - 验证 `CONFIG_FILE_PATH` 是否指向正确的 YAML 文件 ## 贡献 欢迎您的贡献！请： 1. Fork 该仓库 2. 创建一个功能分支 3. 修改代码并编写测试 4. 运行 linter（后端：`ruff`，前端：`eslint`） 5. 提交 pull request ## CI/CD 该项目包含 GitHub Actions 工作流： - **pre_commit.yml**：运行代码检查和代码质量校验 - **build_project.yml**：构建并测试应用程序 ## 许可证 MIT 许可证 - 详情请参阅 [LICENSE](./LICENSE) 文件。 Copyright (c) 2024 dmitriyvasil@gmail.com ## 作者 Dmitriy Vasilievich - Email: dmitriyvasil@gmail.com - GitHub: [dmitriyVasilievich1986](https://github.com/dmitriyVasilievich1986) ## 鸣谢 使用现代开源技术构建： - FastAPI - 优雅的 Python API 框架 - React - 强大的 UI 库 - Material-UI - 精美的组件库 - Cryptography 库 - 安全的加密 **注意**：这是一个旨在供个人或小团队使用的自托管解决方案。对于企业级部署，请考虑额外的安全强化、审计日志和合规性要求。

标签：AV绕过, Docker, FastAPI, React, Syscalls, 安全防御评估, 密码管理器, 端到端加密, 自托管, 请求拦截, 逆向工具