更新记录

1.0.1（2026-07-28）

无

平台兼容性

uni-app(3.99)

其他

CSIS SQLCipher

简介

CSIS SQLCipher 是面向 uni-app App-Android 的 UTS 原生插件，基于 SQLCipher 4 提供加密 SQLite 数据库的打开、查询、执行和关闭能力。插件适用于 CSIS Pad 的本地数据存储与备份导入场景。

支持范围

• 平台：uni-app App-Android
• Android 最低版本：API 23
• 数据库引擎：net.zetetic:sqlcipher-android:4.17.0
• 需要使用自定义基座或正式原生构建，普通 H5、微信小程序和 iOS 不支持

安装与构建

将插件放置在项目的 src/uni_modules/csis-sqlcipher/ 目录下，并在 HBuilderX 中重新运行自定义基座或重新打包 App。修改 utssdk/app-android 下的原生文件后，必须重新编译原生基座才会生效。

快速开始

import {
  closeDatabase,
  executeSql,
  isOpenDatabase,
  openDatabase,
  selectSql
} from '@/uni_modules/csis-sqlcipher'

const database = {
  name: 'app_data.db',
  path: plus.io.convertLocalFileSystemURL('_doc/app_data.db')
}

openDatabase({
  ...database,
  integrityCheck: true,
  success() {
    console.log('数据库打开成功')
  },
  fail(error) {
    console.error('数据库打开失败', error.errMsg)
  }
})

selectSql({
  ...database,
  sql: 'SELECT * FROM user_info',
  success(rows) {
    console.log(rows)
  }
})

executeSql({
  ...database,
  sql: 'PRAGMA foreign_keys = ON',
  success() {
    console.log('SQL 执行成功')
  }
})

closeDatabase({
  name: database.name,
  success() {
    console.log('数据库已关闭')
  }
})

API

openDatabase(options)

打开已有的 SQLCipher 数据库。数据库文件必须存在，插件不会通过错误密钥创建可用数据库。

selectSql(options)

selectSql({
  name: database.name,
  sql: 'SELECT id, name FROM user_info',
  success(rows) {},
  fail(error) {}
})

查询成功时，success 接收行数组；失败时，error.errMsg 包含原生错误信息。

executeSql(options)

用于执行 INSERT、UPDATE、DELETE、CREATE TABLE 等非查询 SQL。

isOpenDatabase(options)

同步返回指定数据库连接是否处于打开状态：

const opened = isOpenDatabase(database)

closeDatabase(options)

关闭指定连接。关闭后再次查询前需要重新调用 openDatabase。

配置数据库名称

数据库名称和路径由调用 openDatabase 时传入的 name、path 决定。name 是连接标识，path 才是实际文件位置；建议两者使用相同的文件名，且同一个 name 始终对应同一个绝对路径。

例如，打开 _doc/customer.db：

const database = {
  name: 'customer.db',
  path: plus.io.convertLocalFileSystemURL('_doc/customer.db')
}

openDatabase({
  ...database,
  success() {},
  fail(error) {
    console.error(error.errMsg)
  }
})

项目若通过 src/utils/db.js 统一管理数据库文件名，只需修改该文件的 DATABASE_NAME，导入、备份和打开逻辑会随之使用新名称。

配置 DATABASE_KEY 密码

当前密码由 Android 原生文件 utssdk/app-android/SqlCipherNative.kt 中的 DATABASE_KEY 常量控制，不需要也不应从 JavaScript 传入。可以替换为自己的高强度随机密码：

object SqlCipherNative {
    private const val DATABASE_KEY = "MyNewStrongKey_2026!"
}

修改密码后，旧数据库不能再使用新密码打开，必须使用新密码重新加密数据库。若使用项目内的 reencrypt-mobile-data.ps1，同步修改其中的 ATTACH DATABASE ... KEY：

ATTACH DATABASE "$targetSqlPath" AS encrypted KEY 'MyNewStrongKey_2026!';

然后执行脚本重新生成加密数据库，并重新构建自定义基座或正式 App，使 Kotlin 中的 DATABASE_KEY 生效。数据库名称的修改不会改变密钥；密码的修改必须同时更新原生常量和数据库生成流程。

加密兼容性

插件采用 SQLCipher 4 默认兼容参数：AES-256、页大小 4096、KDF 迭代次数 256000、HMAC 开启。使用桌面 SQLCipher 或其他插件生成数据库时，必须使用完全一致的密钥和参数；仅修改文件名不会改变数据库加密格式。

注意事项

• 数据库操作是异步的，请在 success 或 complete 回调中继续后续流程。
• 同一个 name 应始终对应同一个绝对路径。
• 原生插件代码或依赖变更后，必须重新构建自定义基座；旧基座不会包含最新 Kotlin/SQLCipher 代码。
• DATABASE_KEY 写在原生代码中，仅适合内部项目使用；正式发布前应改为 Android Keystore 等安全的密钥管理方案。