![[AWS] dynamodb-local本地数据库安装以及dynamoose模块连接dynamodb-local：TaoToken统一Key接入与config.toml骨架](http://pic.xiahunao.cn/yaotu/[AWS] dynamodb-local本地数据库安装以及dynamoose模块连接dynamodb-local：TaoToken统一Key接入与config.toml骨架)
1. 本地 NoSQL 开发环境为什么值得折腾如果你正在用 Node.js 写后端又不想在开发阶段就依赖线上数据库那 dynamodb-local 基本是最省心的选择之一。它是 AWS DynamoDB 的本地调试版本跑在你自己的机器上接口和云端保持一致但数据只存在本地随便删随便造不用担心污染线上表。配合 dynamoose 这个对象建模模块写起来的手感和 mongoose 操作 MongoDB 很像不用去手写那一堆AttributeValue的嵌套结构。我这次要交付的是一条完整链路用 Docker 起一个 dynamodb-local 容器用 aws-cli 建一张本地表验证服务活着再用 dynamoose 在 Node.js 里连上去做增删查。同时把 AI 工具链的 Key 管理也顺手收拢一下——本地开发经常要同时开好几个 AI 辅助工具每个都单独配 Key 很烦用 TaoToken 的统一 Key 通道可以少配几处。整篇的目标很明确你照着敲完本地 NoSQL 环境一次跑通。适合谁看正在学 AWS DynamoDB 但不想开云账号的 Node.js 开发者想给项目加本地数据库做集成测试的同学以及已经在用 dynamoose 但连接老是报错的人。下面从环境准备开始一步步来。2. TaoToken 前置统一 Key 与 API 通道准备在进入数据库配置之前先把 AI 工具这边的 Key 通道理清楚。本地开发时我通常会开 Claude Code 或者一些编码辅助工具如果每个工具都去单独申请和配置 Key切换起来很乱。TaoToken 提供的是一个统一的 Key 和 API 通道你申请一次后面不同工具都指向同一个入口就行。具体操作路径是这样先到官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册账号然后进控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 创建 API Key。拿到 Key 之后如果你要用 Claude Code 这类编码工具可以参考 Coding Plan 的配置说明 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 里面有针对长期编码场景的接入方式。API 的基础地址是 https://taotoken.net/api 注意这个地址不带 UTM 参数配置到工具里时直接用这个。Key 的管理入口在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。如果你只是想先验证模型通不通可以用模型对话页面 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 快速试一下。这一步不是必须和 dynamodb-local 绑在一起但把 Key 收拢好之后后面写代码时调用 AI 辅助就不用反复找 Key 了。下面进入正题。3. 可复制配置dynamodb-local 安装与 dynamoose 连接3.1 用 Docker Compose 起 dynamodb-local我选 Docker 方式因为干净、好删、端口可控。先建一个docker-compose-dynamodb-local.yamlversion: 3 services: dynamodb: image: amazon/dynamodb-local hostname: dynamodb-local container_name: dynamodb-local ports: - 8042:8000这里把容器内的 8000 端口映射到宿主机的 8042避免和你机器上其他服务撞端口。启动命令docker-compose -f docker-compose-dynamodb-local.yaml up -d起来之后用docker ps -a看一眼应该能看到dynamodb-local容器在运行。如果容器秒退多半是端口被占换个宿主机端口再试。3.2 用 aws-cli 建表验证服务先装 aws-cli v2curl https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip -o awscliv2.zip unzip awscliv2.zip sudo ./aws/install装完执行aws configureregion 随便填一个比如us-east-1Access Key 和 Secret 本地调试可以填test因为 dynamodb-local 不校验真实凭证。然后建表aws dynamodb --endpoint-url http://127.0.0.1:8042 create-table \ --table-name demo-customer-info \ --attribute-definitions AttributeNamecustomerId,AttributeTypeS \ --key-schema AttributeNamecustomerId,KeyTypeHASH \ --provisioned-throughput ReadCapacityUnits5,WriteCapacityUnits5参数逐个说清楚--endpoint-url指向本地 8042这是访问容器内 DynamoDB 的入口--table-name是表名--attribute-definitions描述主键属性的名字和类型S表示字符串--key-schema定义主键HASH就是分区键--provisioned-throughput是读写吞吐本地实例其实不限制填 5 就行。执行成功会返回一段 JSON包含TableDescription和TableStatus: ACTIVE。3.3 dynamoose 连接配置在 Node.js 项目里装依赖npm install --save dynamoose连接本地实例的核心就一行dynamoose.aws.ddb.local()完整测试脚本const dynamoose require(dynamoose); // 指向本地 dynamodb-local dynamoose.aws.ddb.local(http://localhost:8042); const Cat dynamoose.model(Cat, { id: Number, name: String, }); async function main() { const garfield new Cat({ id: 666, name: Garfield }); await garfield.save(); console.log(save ok); const badCat await Cat.get(666); console.log(Never trust a smiling cat. - ${badCat.name}); } main().catch((err) console.error(err));跑起来如果打印出save ok和Never trust a smiling cat. - Garfield说明整条链路通了。注意dynamoose.aws.ddb.local()这个方法会覆盖默认的 AWS 端点不需要你再手动传 region 和 credentials。3.4 config.toml 骨架如果你用支持 TOML 配置的工具链可以放一个骨架统一管理本地和远端环境[aws] region us-east-1 access_key test secret_key test [dynamodb] endpoint http://localhost:8042 table_prefix demo- [taotoken] api_base https://taotoken.net/api api_key 你的_TaoToken_Key本地开发时endpoint指向 localhost切到远端时把 endpoint 换成真实地址、access_key 换成真实凭证即可。TaoToken 的 Key 放在这里AI 工具读取同一个配置省得散落各处。4. 验证请求与成功结果验证分两层。第一层是数据库服务本身用 aws-cli 列一下表aws dynamodb --endpoint-url http://127.0.0.1:8042 list-tables返回里应该能看到demo-customer-info。第二层是 dynamoose 的读写就是上面那段脚本。我实测下来第一次跑最容易卡在ResourceNotFoundException原因是 dynamoose 默认会去连真实的 AWS 端点而不是本地。确认你调用了dynamoose.aws.ddb.local()并且地址端口和 compose 文件里的映射一致。再补一个用 aws-cli 写入再读出的验证确保表结构没问题aws dynamodb --endpoint-url http://127.0.0.1:8042 put-item \ --table-name demo-customer-info \ --item {customerId: {S: c001}, name: {S: Alice}} aws dynamodb --endpoint-url http://127.0.0.1:8042 get-item \ --table-name demo-customer-info \ --key {customerId: {S: c001}}能读到 Alice 就说明本地 NoSQL 环境完全就绪。这时候你再去跑 dynamoose 的模型操作心里就有底了。5. 本篇常见错排查报错一Could not connect to the endpoint URL。先docker ps看容器在不在再curl http://localhost:8042看端口通不通。如果容器在但端口不通检查 compose 里的端口映射是不是写成了8042:8042容器内监听的是 8000。报错二ResourceNotFoundException: Cannot do operations on a non-existent table。dynamoose 建表有延迟或者你连到了错误的端点。确认dynamoose.aws.ddb.local()的地址和 aws-cli 的--endpoint-url是同一个。另外 dynamoose 默认create为 false需要显式传{ create: true }才会自动建表。报错三UnrecognizedClientException或凭证相关错误。本地实例不校验凭证但 SDK 仍然要求有值。在环境变量里设AWS_ACCESS_KEY_IDtest和AWS_SECRET_ACCESS_KEYtest即可或者用aws configure填上。报错四端口 8042 被占用。换一个宿主机端口比如8043:8000然后所有配置里的 8042 同步改成 8043。这个坑我踩过改了一处忘了改另一处排查了半天。报错五dynamoose 版本差异导致 API 不同。老版本用dynamoose.local()新版本是dynamoose.aws.ddb.local()。看你装的版本npm ls dynamoose确认一下按对应版本的文档写。6. 接入文档与 Key 管理入口本地环境跑通之后如果你要把 AI 辅助工具也接进来Key 和文档入口集中放一下。API Key 创建和管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。API 基础地址统一用 https://taotoken.net/api 不要带多余参数。如果你主要是长期写代码、跑 Agent 任务建议直接看 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 配置一次后面省事。Claude Code 相关的接入说明在 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaude-code-anthropicutm_campaignrewrite 。只是想快速验证模型能不能用模型对话页面 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 点开就能试。最后提醒一句dynamodb-local 的数据默认存在容器内docker-compose down之后数据就没了。如果你想让本地数据持久化可以在 compose 里加一个 volume 挂载把容器内的数据目录映射出来。这个我下次单独写一篇今天先把环境跑通。
1. 本地 NoSQL 开发环境为什么值得折腾如果你正在用 Node.js 写后端又不想在开发阶段就依赖线上数据库那 dynamodb-local 基本是最省心的选择之一。它是 AWS DynamoDB 的本地调试版本跑在你自己的机器上接口和云端保持一致但数据只存在本地随便删随便造不用担心污染线上表。配合 dynamoose 这个对象建模模块写起来的手感和 mongoose 操作 MongoDB 很像不用去手写那一堆AttributeValue的嵌套结构。我这次要交付的是一条完整链路用 Docker 起一个 dynamodb-local 容器用 aws-cli 建一张本地表验证服务活着再用 dynamoose 在 Node.js 里连上去做增删查。同时把 AI 工具链的 Key 管理也顺手收拢一下——本地开发经常要同时开好几个 AI 辅助工具每个都单独配 Key 很烦用 TaoToken 的统一 Key 通道可以少配几处。整篇的目标很明确你照着敲完本地 NoSQL 环境一次跑通。适合谁看正在学 AWS DynamoDB 但不想开云账号的 Node.js 开发者想给项目加本地数据库做集成测试的同学以及已经在用 dynamoose 但连接老是报错的人。下面从环境准备开始一步步来。2. TaoToken 前置统一 Key 与 API 通道准备在进入数据库配置之前先把 AI 工具这边的 Key 通道理清楚。本地开发时我通常会开 Claude Code 或者一些编码辅助工具如果每个工具都去单独申请和配置 Key切换起来很乱。TaoToken 提供的是一个统一的 Key 和 API 通道你申请一次后面不同工具都指向同一个入口就行。具体操作路径是这样先到官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册账号然后进控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 创建 API Key。拿到 Key 之后如果你要用 Claude Code 这类编码工具可以参考 Coding Plan 的配置说明 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 里面有针对长期编码场景的接入方式。API 的基础地址是 https://taotoken.net/api 注意这个地址不带 UTM 参数配置到工具里时直接用这个。Key 的管理入口在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。如果你只是想先验证模型通不通可以用模型对话页面 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 快速试一下。这一步不是必须和 dynamodb-local 绑在一起但把 Key 收拢好之后后面写代码时调用 AI 辅助就不用反复找 Key 了。下面进入正题。3. 可复制配置dynamodb-local 安装与 dynamoose 连接3.1 用 Docker Compose 起 dynamodb-local我选 Docker 方式因为干净、好删、端口可控。先建一个docker-compose-dynamodb-local.yamlversion: 3 services: dynamodb: image: amazon/dynamodb-local hostname: dynamodb-local container_name: dynamodb-local ports: - 8042:8000这里把容器内的 8000 端口映射到宿主机的 8042避免和你机器上其他服务撞端口。启动命令docker-compose -f docker-compose-dynamodb-local.yaml up -d起来之后用docker ps -a看一眼应该能看到dynamodb-local容器在运行。如果容器秒退多半是端口被占换个宿主机端口再试。3.2 用 aws-cli 建表验证服务先装 aws-cli v2curl https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip -o awscliv2.zip unzip awscliv2.zip sudo ./aws/install装完执行aws configureregion 随便填一个比如us-east-1Access Key 和 Secret 本地调试可以填test因为 dynamodb-local 不校验真实凭证。然后建表aws dynamodb --endpoint-url http://127.0.0.1:8042 create-table \ --table-name demo-customer-info \ --attribute-definitions AttributeNamecustomerId,AttributeTypeS \ --key-schema AttributeNamecustomerId,KeyTypeHASH \ --provisioned-throughput ReadCapacityUnits5,WriteCapacityUnits5参数逐个说清楚--endpoint-url指向本地 8042这是访问容器内 DynamoDB 的入口--table-name是表名--attribute-definitions描述主键属性的名字和类型S表示字符串--key-schema定义主键HASH就是分区键--provisioned-throughput是读写吞吐本地实例其实不限制填 5 就行。执行成功会返回一段 JSON包含TableDescription和TableStatus: ACTIVE。3.3 dynamoose 连接配置在 Node.js 项目里装依赖npm install --save dynamoose连接本地实例的核心就一行dynamoose.aws.ddb.local()完整测试脚本const dynamoose require(dynamoose); // 指向本地 dynamodb-local dynamoose.aws.ddb.local(http://localhost:8042); const Cat dynamoose.model(Cat, { id: Number, name: String, }); async function main() { const garfield new Cat({ id: 666, name: Garfield }); await garfield.save(); console.log(save ok); const badCat await Cat.get(666); console.log(Never trust a smiling cat. - ${badCat.name}); } main().catch((err) console.error(err));跑起来如果打印出save ok和Never trust a smiling cat. - Garfield说明整条链路通了。注意dynamoose.aws.ddb.local()这个方法会覆盖默认的 AWS 端点不需要你再手动传 region 和 credentials。3.4 config.toml 骨架如果你用支持 TOML 配置的工具链可以放一个骨架统一管理本地和远端环境[aws] region us-east-1 access_key test secret_key test [dynamodb] endpoint http://localhost:8042 table_prefix demo- [taotoken] api_base https://taotoken.net/api api_key 你的_TaoToken_Key本地开发时endpoint指向 localhost切到远端时把 endpoint 换成真实地址、access_key 换成真实凭证即可。TaoToken 的 Key 放在这里AI 工具读取同一个配置省得散落各处。4. 验证请求与成功结果验证分两层。第一层是数据库服务本身用 aws-cli 列一下表aws dynamodb --endpoint-url http://127.0.0.1:8042 list-tables返回里应该能看到demo-customer-info。第二层是 dynamoose 的读写就是上面那段脚本。我实测下来第一次跑最容易卡在ResourceNotFoundException原因是 dynamoose 默认会去连真实的 AWS 端点而不是本地。确认你调用了dynamoose.aws.ddb.local()并且地址端口和 compose 文件里的映射一致。再补一个用 aws-cli 写入再读出的验证确保表结构没问题aws dynamodb --endpoint-url http://127.0.0.1:8042 put-item \ --table-name demo-customer-info \ --item {customerId: {S: c001}, name: {S: Alice}} aws dynamodb --endpoint-url http://127.0.0.1:8042 get-item \ --table-name demo-customer-info \ --key {customerId: {S: c001}}能读到 Alice 就说明本地 NoSQL 环境完全就绪。这时候你再去跑 dynamoose 的模型操作心里就有底了。5. 本篇常见错排查报错一Could not connect to the endpoint URL。先docker ps看容器在不在再curl http://localhost:8042看端口通不通。如果容器在但端口不通检查 compose 里的端口映射是不是写成了8042:8042容器内监听的是 8000。报错二ResourceNotFoundException: Cannot do operations on a non-existent table。dynamoose 建表有延迟或者你连到了错误的端点。确认dynamoose.aws.ddb.local()的地址和 aws-cli 的--endpoint-url是同一个。另外 dynamoose 默认create为 false需要显式传{ create: true }才会自动建表。报错三UnrecognizedClientException或凭证相关错误。本地实例不校验凭证但 SDK 仍然要求有值。在环境变量里设AWS_ACCESS_KEY_IDtest和AWS_SECRET_ACCESS_KEYtest即可或者用aws configure填上。报错四端口 8042 被占用。换一个宿主机端口比如8043:8000然后所有配置里的 8042 同步改成 8043。这个坑我踩过改了一处忘了改另一处排查了半天。报错五dynamoose 版本差异导致 API 不同。老版本用dynamoose.local()新版本是dynamoose.aws.ddb.local()。看你装的版本npm ls dynamoose确认一下按对应版本的文档写。6. 接入文档与 Key 管理入口本地环境跑通之后如果你要把 AI 辅助工具也接进来Key 和文档入口集中放一下。API Key 创建和管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。API 基础地址统一用 https://taotoken.net/api 不要带多余参数。如果你主要是长期写代码、跑 Agent 任务建议直接看 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 配置一次后面省事。Claude Code 相关的接入说明在 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaude-code-anthropicutm_campaignrewrite 。只是想快速验证模型能不能用模型对话页面 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 点开就能试。最后提醒一句dynamodb-local 的数据默认存在容器内docker-compose down之后数据就没了。如果你想让本地数据持久化可以在 compose 里加一个 volume 挂载把容器内的数据目录映射出来。这个我下次单独写一篇今天先把环境跑通。
