Abracadabra项目部署与使用全指南

项目概述

Abracadabra（魔曰）是一个创新的数据加密处理工具，提供了两种独特的加密方式：传统加密和文言文仿真加密。该项目支持多种部署方式，包括JavaScript环境和WebAssembly环境，能够满足不同场景下的安全需求。

JavaScript环境部署

安装方式

Abracadabra提供了两种主要的JavaScript安装方式：

1. NPM安装（推荐） 通过包管理器安装是最简单的方式：

   npm install abracadabra-cn
   

2. 网页直接引用 对于不使用构建工具的项目，可以直接引入UMD格式的脚本文件：

   <script src="path/to/abracadabra-cn.umd.cjs"></script>
   

核心API详解

初始化

创建Abracadabra实例时需要指定输入输出模式：

const abra = new Abracadabra(inputMode, outputMode);

• 支持的模式：
  • TEXT：处理字符串类型数据
  • UINT8：处理Uint8Array类型数据（适合二进制数据）

传统加密方法Input()

abra.Input(input, mode, key, q);

参数说明：

• input：要处理的数据（类型需与初始化时指定的一致）
• mode：处理模式（ENCRYPT/DECRYPT/AUTO）
• key：加密密钥（可选，默认"ABRACADABRA"）
• q：是否隐藏标志位（可选，默认false）

文言文仿真加密Input_Next()

abra.Input_Next(input, mode, key, q, r, p, l);

新增参数说明：

• r：随机度（0-100，默认50）
• p：是否使用骈文句式
• l：是否使用逻辑句式

获取输出Output()

const result = abra.Output();

注意：必须先调用Input()或Input_Next()方法后才能调用Output()

自行编译指南

如需自定义功能，可以自行编译项目：

1. 安装依赖：

   npm install
   

2. 执行编译：

   npm run build
   

3. 测试验证：

   npm run test
   

WebAssembly环境部署

基本使用

WebAssembly版本适合需要更高性能或需要在多种语言环境中集成的场景。

输入格式

WebAssembly模块接受JSON格式的输入：

{
  "method": "NEXT|OLD",
  "inputType": "TEXT|UINT8",
  "outputType": "TEXT|UINT8",
  "input": "输入数据",
  "mode": "ENCRYPT|DECRYPT|AUTO",
  "key": "加密密钥",
  "q": true|false,
  "r": 0-100,
  "p": true|false,
  "l": true|false
}

命令行调用示例

echo '{"method":"NEXT","mode":"ENCRYPT","input":"测试数据"}' | wasmtime abracadabra-cn.wasm

Python集成示例

import wasmtime

def run_wasm(wasm_file, input_json):
    engine = wasmtime.Engine()
    module = wasmtime.Module.from_file(engine, wasm_file)
    store = wasmtime.Store(engine)
    linker = wasmtime.Linker(engine)
    wasi = wasmtime.WasiConfig()
    wasi.stdin_file = input_json
    linker.define_wasi()
    store.set_wasi(wasi)
    instance = linker.instantiate(store, module)
    instance.exports(store)["_start"](store)

自行编译WASM模块

1. 确保已安装Javy工具链
2. 构建JavaScript版本
3. 使用Javy编译为WASM：

   javy build abracadabra-cn-javy.js -o output.wasm
   

最佳实践建议

1. 密钥管理：建议不要使用默认密钥，应使用自定义强密码
2. 错误处理：妥善处理可能抛出的错误，特别是解密时的校验错误
3. 性能考量：对于高频操作，建议使用WebAssembly版本
4. 安全考虑：文言文加密虽然隐蔽，但不建议单独用于高安全性需求场景

常见问题解答

Q: 为什么解密时出现校验错误？ A: 可能是密钥不正确或数据在传输过程中被修改

Q: 如何提高文言文加密的随机性？ A: 调整r参数到更高的值（最大100）

Q: 二进制数据如何处理？ A: 使用UINT8模式，输入输出都使用Uint8Array类型

通过本指南，您应该能够顺利部署和使用Abracadabra项目的各项功能。无论是简单的网页加密需求，还是复杂的系统集成，Abracadabra都提供了灵活的解决方案。