Maas-Model-platform/backend/migrations/DECRYPT_TOOL_GUIDE.md

身份证号解密工具使用指南

概述

decrypt_id_card.py 是一个命令行工具，用于解密数据库中AES加密存储的身份证号。此工具仅供系统管理员在必要时使用。

安全警告

⚠️ 重要提示：

• 此工具仅供授权管理员使用
• 解密后的数据包含敏感个人信息
• 请妥善保管解密结果，不要泄露
• 使用后请清除终端历史记录
• 不要将此工具和密钥提交到版本控制系统

---

前置条件

1. 环境要求

• Python 3.7+
• 已安装项目依赖
• 配置正确的 AES_ENCRYPTION_KEY

2. 配置检查

# 检查 .env 文件中是否有 AES_ENCRYPTION_KEY
cd backend
cat .env | grep AES_ENCRYPTION_KEY

# 如果没有，运行密钥生成工具
python generate_aes_key.py

3. 权限要求

• 数据库读取权限
• 服务器文件访问权限
• 环境变量访问权限

---

使用方法

基本语法

cd backend
python decrypt_id_card.py [选项] [参数]

命令选项

1. 查看帮助信息

python decrypt_id_card.py

输出：

============================================================
身份证号解密工具
============================================================

用法:
  1. 按用户ID解密:
     python decrypt_id_card.py <user_id>

  2. 按用户名解密:
     python decrypt_id_card.py --username <username>

  3. 列出所有已认证用户:
     python decrypt_id_card.py --list

============================================================
注意事项:
1. 此工具仅供管理员使用
2. 需要正确配置 AES_ENCRYPTION_KEY
3. 请妥善保管解密后的数据
============================================================

2. 列出所有已认证用户

python decrypt_id_card.py --list

输出示例：

================================================================================
已认证用户列表
================================================================================
用户ID                                   用户名          真实姓名   身份证号            
--------------------------------------------------------------------------------
b3c34fa9-c5ff-404e-b7b8-852f4e2d1cd7    mbx            王五       110105199001011234  
a1b2c3d4-e5f6-7890-abcd-ef1234567890    testuser       张三       320106198506011234  
================================================================================
共 2 个已认证用户
================================================================================

3. 按用户ID解密

python decrypt_id_card.py b3c34fa9-c5ff-404e-b7b8-852f4e2d1cd7

输出示例：

============================================================
用户信息
============================================================
用户ID: b3c34fa9-c5ff-404e-b7b8-852f4e2d1cd7
用户名: mbx
真实姓名: 王五
认证状态: verified
身份证号: 110105199001011234
============================================================

4. 按用户名解密

python decrypt_id_card.py --username mbx

输出示例：

============================================================
用户信息
============================================================
用户ID: b3c34fa9-c5ff-404e-b7b8-852f4e2d1cd7
用户名: mbx
真实姓名: 王五
认证状态: verified
身份证号: 110105199001011234
============================================================

---

使用场景

场景1：验证加密功能

在部署后验证加密是否正常工作：

# 1. 用户提交实名认证
# 2. 使用工具解密验证
python decrypt_id_card.py --username test_user

# 3. 对比用户提交的原始数据

场景2：数据审计

定期审计已认证用户：

# 导出所有已认证用户信息
python decrypt_id_card.py --list > verified_users_$(date +%Y%m%d).txt

# 查看导出文件
cat verified_users_20260331.txt

场景3：用户支持

用户忘记身份证号时提供支持：

# 按用户名查询
python decrypt_id_card.py --username user123

# 提供给用户（脱敏处理）
# 例如：110105********1234

场景4：数据迁移

迁移到新系统前导出数据：

# 导出所有数据
python decrypt_id_card.py --list > migration_data.txt

# 处理导出的数据
# 在新系统中重新加密

---

输出格式

单用户查询输出

============================================================
用户信息
============================================================
用户ID: <UUID>
用户名: <username>
真实姓名: <real_name>
认证状态: <verified/unverified>
身份证号: <decrypted_id_card>
============================================================

列表查询输出

================================================================================
已认证用户列表
================================================================================
用户ID                                   用户名          真实姓名   身份证号            
--------------------------------------------------------------------------------
<user_id>                                <username>     <name>     <id_card>
...
================================================================================
共 X 个已认证用户
================================================================================

---

错误处理

错误1：用户不存在

错误: 用户不存在

原因：提供的用户ID或用户名不存在

解决方案：

# 检查用户是否存在
python decrypt_id_card.py --list

错误2：未提交身份证号

用户 xxx 未提交身份证号

原因：用户未完成实名认证

解决方案：提醒用户完成实名认证

错误3：解密失败

解密失败: AES解密失败: ...
可能原因:
1. AES密钥不正确
2. 数据已损坏
3. 这是旧数据（未加密）

原因：

1. .env 中的 AES_ENCRYPTION_KEY 不正确
2. 数据库中的数据已损坏
3. 数据是迁移前的明文数据

解决方案：

# 1. 检查密钥配置
cat backend/.env | grep AES_ENCRYPTION_KEY

# 2. 如果是旧数据，需要用户重新提交认证

# 3. 如果密钥丢失，数据无法恢复

错误4：数据库连接失败

sqlalchemy.exc.OperationalError: ...

原因：无法连接到数据库

解决方案：

# 检查数据库配置
cat backend/.env | grep DATABASE_URL

# 测试数据库连接
psql -U your_username -d your_database -c "SELECT 1;"

---

安全最佳实践

1. 访问控制

# 限制工具文件权限（仅所有者可执行）
chmod 700 backend/decrypt_id_card.py

# 限制密钥文件权限
chmod 600 backend/.env

2. 审计日志

建议记录所有解密操作：

# 创建审计日志
echo "$(date) - User: $(whoami) - Action: decrypt - Target: $1" >> /var/log/id_card_decrypt.log

# 查看审计日志
tail -f /var/log/id_card_decrypt.log

3. 输出重定向

避免敏感信息显示在终端：

# 输出到文件
python decrypt_id_card.py --list > /tmp/secure_output.txt

# 查看后立即删除
cat /tmp/secure_output.txt
shred -u /tmp/secure_output.txt

4. 清除历史记录

使用后清除命令历史：

# 清除当前会话历史
history -c

# 或者使用空格前缀（不记录到历史）
 python decrypt_id_card.py --username test

---

高级用法

批量导出（带脱敏）

创建一个脚本进行批量导出并脱敏：

#!/bin/bash
# export_masked.sh

python decrypt_id_card.py --list | while read line; do
    # 脱敏处理：只显示前6位和后4位
    echo "$line" | sed 's/\([0-9]\{6\}\)[0-9]\{8\}\([0-9X]\{4\}\)/\1********\2/g'
done

与其他工具集成

# 导出为CSV格式
python decrypt_id_card.py --list | \
  awk 'NR>3 && NF>0 {print $1","$2","$3","$4}' > users.csv

# 导出为JSON格式（需要修改工具）
# 或使用 jq 处理

---

工具维护

更新工具

如果需要添加新功能，修改 decrypt_id_card.py：

# 示例：添加导出为JSON功能
def export_to_json():
    """导出为JSON格式"""
    import json
    db = SessionLocal()
    try:
        users = db.query(User).filter(
            User.is_verified == "verified"
        ).all()
        
        result = []
        for user in users:
            decrypted_id_card = encryption_service.aes_decrypt(user.id_card)
            result.append({
                "user_id": user.id,
                "username": user.username,
                "real_name": user.real_name,
                "id_card": decrypted_id_card
            })
        
        print(json.dumps(result, ensure_ascii=False, indent=2))
    finally:
        db.close()

测试工具

# 创建测试用户
# 提交测试认证
# 运行解密工具验证
python decrypt_id_card.py --username test_user

---

常见问题

Q1: 可以在生产环境使用吗？

A: 可以，但必须：

• 有明确的使用理由
• 获得授权
• 记录操作日志
• 遵守数据保护法规

Q2: 解密后的数据如何处理？

A:

• 仅用于授权目的
• 使用后立即删除
• 不要存储在不安全的位置
• 不要通过不安全的渠道传输

Q3: 密钥丢失怎么办？

A:

• 已加密数据无法恢复
• 需要用户重新提交认证
• 强烈建议备份密钥

Q4: 可以批量修改身份证号吗？

A:

• 不建议直接修改加密数据
• 应该让用户重新提交
• 如必须修改，需要：
  1. 解密旧数据
  2. 修改明文
  3. 重新加密
  4. 更新数据库

---

相关文档

• 数据库迁移指南
• 安装指南
• 加密服务文档

---

版本历史

版本	日期	更新内容
v1.0	2026-03-31	初始版本

---

许可和责任

使用此工具即表示您同意：

1. 仅用于授权目的
2. 遵守相关法律法规
3. 保护用户隐私
4. 承担使用责任

未经授权使用此工具可能违反法律！