树洞留言墙（HarmonyOS 应用 + 华为云 Serverless）

使用 ArkTS、FunctionGraph 和 RDS for MySQL 构建一个支持匿名留言、主题论坛和管理员后台的 HarmonyOS 端云一体化应用。

项目	内容
适合谁	有 HarmonyOS 或后端基础、想学习端云一体化开发的工程师
难度与耗时	入门 · 新手预计 2.5–3.5 小时
你将学到	ArkTS 端侧开发；FunctionGraph 云函数编写规范；APIG 网关与触发器配置；RDS MySQL 表设计与中文编码处理
你将完成	可运行的 HarmonyOS 应用、13 个云函数、5 张数据表及端云联调验收
验证环境	HarmonyOS / DevEco Studio / Node.js 18.15 · 最后验证于 2026-08-14

选择你的阅读路线：想先看到结果 → 快速体验 · 想完整学习 → 完整实践 · 遇到问题 → 验收与排障

1. 案例概览

树洞留言墙是一个匿名倾诉 + 主题论坛的社区型应用，用于演示「HarmonyOS 端侧 + 华为云 Serverless 云侧」的完整端云一体化开发流程。它覆盖了账号注册登录、内容发布、检索与管理，是一次从零搭建可运行端云应用的完整实践；其中沉淀的云函数规范、中文编码处理和网关配置经验，可复用到任何 FunctionGraph + RDS 的后端场景。

核心功能与体验

1. 用户用邮箱注册并登录 → 进入留言墙，可匿名发布和浏览留言。
2. 用户创建 / 搜索主题论坛并发帖 → 论坛列表按关键字检索，帖子分页展示。
3. 用户查看个人发言历史 → 留言墙与论坛发言聚合展示，支持关键字搜索。
4. 管理员登录 → 管理留言、论坛和用户，可删除 / 恢复留言、封禁 / 解封论坛与用户。

用户个人页	管理员页

技术方案一览

flowchart LR
    A["HarmonyOS App（ArkTS，6 页面）"] -->|HTTPS| B["APIG 专享版网关"]
    B -->|DEDICATEDGATEWAY 触发器| C["FunctionGraph 云函数（Node.js，13 个）"]
    C -->|VPC 内网 TCP 3306| D["RDS for MySQL（forum_db，5 张表）"]

一次核心业务操作（如发布留言）的链路：App 通过 APIG 调试域名发起 HTTPS 请求，APIG 按「路径 + 方法」匹配到对应云函数，云函数在 VPC 内网访问 MySQL 完成读写，再把结果原路返回App。端侧不直接连数据库，APIG 是唯一公网入口。

层级	技术/产品	验证版本	作用
端侧	ArkTS / ArkUI	DevEco Studio	6 个页面（登录、留言墙、论坛列表、论坛详情、个人历史、管理员面板）
云侧	FunctionGraph	Node.js 18.15	13 个云函数承载注册、登录、留言、论坛、管理业务
网关	APIG 专享版	—	统一公网入口，按路径 + 方法路由到函数
数据	RDS for MySQL	MySQL	forum_db 库：users / messages / forums / forum_posts / user_tokens
工具	DevEco / hvigor / hdc	—	编译、构建与安装 HarmonyOS 应用

边界说明

• 本案例面向学习与演示，云侧认证采用 NONE（联调），不包含正式上架所需的鉴权、限流、审计等生产化改造。
• 数据库初始化依赖一次性 db-init 函数，生产初始化完成后需禁用或删除其触发器。

2. 开始之前

先确认下面的准备条件，通用安装教程优先参考官方文档。

环境与资源

项目	要求	检查或获取方式
基础知识	ArkTS、HTTP、数据库基础	可选：HarmonyOS 官方 ArkTS 教程
开发环境	Windows/macOS、DevEco Studio、Node.js、Python 3.8+	node -v、python --version、DevEco 界面路径
Python 依赖	华为云 SDK（仅自动部署路线需要）	pip install huaweicloudsdkcore huaweicloudsdkfunctiongraph huaweicloudsdkapig
测试设备	模拟器或真机	hdc list targets
账号与服务	华为云账号（已实名）、开通 FunctionGraph / APIG / RDS / VPC	控制台开通，全程同一区域
权限与网络	函数与数据库同 VPC，安全组放通 3306	VPC 控制台检查连通性

费用与配额

资源	建议规格	计费方式	实践预计费用	结束后如何处理
RDS for MySQL	入门规格	按需	数元（按使用时长）	删除实例
APIG 专享版	基础实例 + 弹性 IP	按需	少量（含公网 IP）	释放实例与 EIP
FunctionGraph	256 MB / 30 s	按调用	少量（免费额度内可能为 0）	删除函数

价格验证日期：2026-08-14。实际价格以华为云价格页为准；使用免费额度时需注意额度与超额风险。

配置与敏感信息

占位符	含义	获取位置	安全存放位置
<region>	区域（如 cn-north-4）	控制台右上角	公开配置
<project_id>	项目 ID	「我的凭证」→ 项目列表	公开配置
<vpc_id> / <subnet_id> / <security_group_id>	网络资源	VPC 控制台	公开配置
<db_host> / <db_user> / <db_password>	数据库连接	RDS 实例详情	.env / 服务端环境变量
<apig_domain>	APIG 调试域名	APIG 分组详情	端侧公开配置
<apig_instance_id> / <apig_group_id>	APIG 实例 / 分组 ID（自动部署）	APIG 实例与分组详情	公开配置
<ak> / <sk>	IAM 访问密钥	仅自动部署路线需要	仅 .env（git 忽略）

• .env、签名私钥、部署请求体和本地产物必须加入 .gitignore。
• 客户端不得包含 AK/SK、数据库密码或长期共享密钥。

3. 快速体验

这条路线面向「先把现成案例跑起来」的读者，目标是在约 1–2 小时（含一次性云环境准备）看到第一个成功结果。原理和完整搭建过程见完整实践。

0）用 AI 辅助配置云环境（可选）

想跳过下面的手动步骤？把本仓库 README.md 与 SKILL.md 交给 AI 编程助手（码道 / CodeArts、Cursor 等），让它读完自动配置并部署云环境：

请阅读本仓库 README.md 与 SKILL.md，帮我自动配置并部署「树洞留言墙」云环境：
1. 按第 2 章「配置与敏感信息」列出需要我填写的占位符（AK/SK、区域、VPC、数据库、APIG 等），等我填好 harmony_cloud/deploy/.env；
2. 打包 13 个云函数为 ZIP（根目录直接是 index.js，不套层）；
3. 运行 deploy.py 与 setup_apig_apis.py 部署云侧，再调用 db-init 建表；
4. 把 APIG 调试域名填入 Config.ets，编译并安装端侧；
5. 按第 5 章验收表逐项联调。
每完成一步报告结果；报错时贴完整日志并定位根因；凭据只写本地 .env，不写入代码、不提交仓库。

注意：AI 只能操作你授权的环境。AK/SK、数据库密码等敏感信息请只放在本地 .env（已被 .gitignore 忽略），不要让 AI 把凭据写进代码或提交。部署完成后，仍建议按下面各步骤的「完成标志」人工复核一遍。

1）获取已验证版本

git clone https://gitcode.com/harmony-practice-center/treehole.git
cd treehole

完成标志：根目录存在 README.md、harmony_app/ 和 harmony_cloud/。

2）准备最小配置

cp harmony_cloud/deploy/.env.example harmony_cloud/deploy/.env

1. 将 .env 中的 AK/SK、区域、VPC、数据库、APIG 占位符替换为第 2 章收集的值。
2. 在 harmony_app/entry/src/main/ets/utils/Config.ets 填入 BASE_URL（APIG 调试域名）。

完成标志：没有未替换占位符；敏感配置不会出现在 git status 中。

3）打包 13 个云函数

仓库不内置 ZIP 产物、也不提交 node_modules（已在 .gitignore 中忽略），部署前需自行打包：每个函数目录执行 npm install 后打成 ZIP，放到 harmony_cloud/deploy/zips/，文件名与函数名一致（根目录直接是 index.js，不套层）。

cd harmony_cloud/functions
mkdir -p ../deploy/zips
for d in register login postMessage getMessages createForum searchForums \
         postForumPost getForumPosts getUserHistory adminManageMessage \
         adminManageForum adminBanUser db-init; do
  (cd "$d" && npm install && zip -r "../../deploy/zips/$d.zip" .)
done

Windows 用户注意：上面的命令依赖 zip，而 Windows 默认不带（Git for Windows 通常也没有 zip.exe，运行会报 zip: command not found）。Windows 下请改用 PowerShell 自带的 Compress-Archive（无需额外安装）：

cd harmony_cloud\functions
New-Item -ItemType Directory -Force ..\deploy\zips | Out-Null
$funcs = 'register','login','postMessage','getMessages','createForum','searchForums',
         'postForumPost','getForumPosts','getUserHistory','adminManageMessage',
         'adminManageForum','adminBanUser','db-init'
foreach ($d in $funcs) {
  Set-Location $d
  npm install
  Compress-Archive -Path * -DestinationPath "..\..\deploy\zips\$d.zip" -Force
  Set-Location ..
}

若仍想用 zip，可先安装 Info-ZIP（如 choco install zip），或改用 WSL / macOS / Linux 环境。npm install 需逐个函数目录执行，网络不佳时会较慢；打包后请确认每个 ZIP 根目录直接是 index.js（不套外层文件夹）。

完成标志：harmony_cloud/deploy/zips/ 下存在 13 个 ZIP，每个 ZIP 根目录含 index.js、db.js、package.json 和 node_modules/mysql2、node_modules/iconv-lite。

4）启动云侧

cd harmony_cloud/deploy
python deploy.py              # 创建函数 + 上传代码 + 配置 VPC/环境变量
python setup_apig_apis.py     # 建 APIG API 并发布 RELEASE（主路径）
curl -X POST "https://<apig_domain>/treehole/db-init" \
  -H "Content-Type: application/json" -d '{"file":"all"}'

主路径用 setup_apig_apis.py，setup_vpc_and_triggers.py 作为备选

完成标志：调用 db-init 后数据库存在 5 张表，管理员 admin@example.com / 654321 已写入。

5）构建并运行端侧

Set-Location 'harmony_app'
ohpm install
hvigorw assembleHap --mode module -p module=entry -p product=default -p buildMode=debug --no-daemon
hdc install -r entry/build/default/outputs/default/entry-default-unsigned.hap

完成标志：生成 HAP 并安装到设备，应用能启动到登录页并完成一次登录。

4. 完整实践

这条路线面向「理解并复现案例」的读者。步骤按真实工作流排列，每一步都有可观察的完成标志。云函数编写规范、代码模板、打包与排障细节见 SKILL.md。

一句话让 AI 工作

不想手动逐项操作？把下面这句话发给码道（华为云 CodeArts 鸿蒙开发智能体，或任意支持 HarmonyOS / Node.js 的 AI 编程助手），即可让它从需求澄清一路推进到端云联调。你也可以把规模、功能换成自己的版本。

我想开发一款「树洞留言墙」HarmonyOS 端云一体化应用：端侧 ArkTS/ArkUI，云侧华为云 FunctionGraph + APIG 专享版 + RDS for MySQL，支持邮箱注册登录、匿名留言墙、主题论坛（发帖/检索/分页）、个人历史聚合、管理员后台（删除/恢复留言、封禁/解封论坛与用户）。

请按照标准研发流程推进：先提问澄清需求，再依次产出 requirements.md、design.md、tasks.md；然后分批实现 13 个云函数（注意双参数 handler、Base64+GBK 中文解码、连接池、字符集、密码哈希）、5 张表的建表 SQL 和 6 个端侧页面；最后给出部署（deploy.py + APIG 触发器）与端云联调验收步骤。

每一步都要有可观察的完成标志，关键节点停下来等我确认。

如何指挥 AI 工作

「一句话」只是开工信号，真正决定质量的是后续每一轮的指挥方式：

• 一次只给一个明确目标：每轮指令聚焦单一产出（需求 / 设计 / 任务 / 某一批代码 / 部署），让 AI 给出可观察结果，而不是一次铺开。
• 要求可观察的完成标志：每步都让 AI 明确「做完是什么样子」，你据此判断能否进入下一步。
• 关键节点人工确认：需求澄清、技术选型、云资源配置、部署上线等不可逆或高成本节点，先看 AI 的方案再放行。
• 把真实报错带回去：编译或部署失败时，把完整日志原文贴给 AI 定位，而不是让它凭空猜测。

下面的步骤 1–5 每一步都附了「推荐指令」，可照此逐条指挥 AI；想对照手动操作时，看同一步骤的「操作」。

步骤 1：开通云服务并收集信息

目标：开通 FunctionGraph / APIG / RDS / VPC，并收集部署所需的全部资源 ID。

为什么这样做：后续所有云侧资源的创建都依赖这些 ID；用同一账号、同一区域、同一 VPC 能避免内网不可达和跨区调用问题。

推荐指令：

请帮我梳理这个案例要开通的云服务和要收集的资源信息：FunctionGraph、APIG 专享版、RDS for MySQL、VPC，以及区域、项目 ID、VPC/子网/安全组、数据库连接、APIG 调试域名、IAM AK/SK 等占位符。把每一项的获取位置和安全存放位置整理成一张表，并给出同账号、同区域、同 VPC 的开通注意事项。

操作：

1. 完成华为云账号注册与实名认证。
2. 在目标区域（如 cn-north-4）开通 FunctionGraph、APIG 专享版、RDS、VPC。
3. 若走自动部署路线，创建 IAM 访问密钥（AK/SK）并授权相关服务权限。
4. 按第 2 章的「配置与敏感信息」表逐项收集并记录。

完成标志：信息清单全部填齐，<region> / <project_id> / <vpc_id> / <subnet_id> / <db_host> 等均可用。

如果失败：最常见的失败是区域不一致或 IAM 权限不足（FSS.0403），见验收与排障。

步骤 2：编写并打包 13 个云函数

目标：在本地把 13 个云函数代码写对，并打成可部署的 ZIP。

为什么这样做：云函数代码有一组必须遵守的约束（双参数 handler、Base64 + GBK 解码、连接池、字符集、密码哈希等），否则部署后必然出问题。

推荐指令：

请按云函数编写规范实现 13 个云函数（register、login、postMessage、getMessages、createForum、searchForums、postForumPost、getForumPosts、getUserHistory、adminManageMessage、adminManageForum、adminBanUser、db-init）。注意：handler 双参数、Base64+GBK 中文解码、mysql2 连接池、utf8mb4 字符集、PBKDF2-SHA256 密码哈希、统一 {code,data,message} 返回。完成后给出每个函数的打包命令与 ZIP 目录结构（根目录直接是 index.js，不套层）。

操作：

1. 按 SKILL.md 的「云函数编写规范」与「代码模板」编写 13 个函数。
2. 每个函数目录执行 npm install，再打成 ZIP 放到 harmony_cloud/deploy/zips/{函数名}.zip（根目录直接是 index.js，不套层）。

完成标志：13 个 ZIP 产物就绪，每个 ZIP 根目录含 index.js、db.js、package.json 和 node_modules/mysql2、node_modules/iconv-lite。

如果失败：Cannot find module 'mysql2/promise' 说明依赖没打进 ZIP，重新打包即可。

步骤 3：部署云侧（手动或自动，二选一）

目标：把 13 个函数部署到华为云，配置 VPC、环境变量和 APIG 触发器，并初始化数据库。

为什么这样做：手动路线便于逐项确认资源状态，自动路线适合批量复用；两条路线产出相同，交叉创建同名资源会导致冲突。

推荐指令：

请编写部署自动化脚本：deploy.py 负责创建函数、上传代码、配置 VPC 与 5 个环境变量（DB_HOST/DB_PORT/DB_USER/DB_PASSWORD/DB_NAME），setup_apig_apis.py 负责创建并发布 APIG API（按「路径 + 方法」路由，发布到 RELEASE）。同时给出 db-init 建表与种子数据（含管理员 admin@example.com / 654321）的调用方式，以及 VPC 内网访问 MySQL 的安全组配置要点。

操作：

1. 选择一条路线：手动在控制台逐项创建（见 SKILL 的「APIG 集成」），或自动用 Python SDK（见 SKILL 的「部署自动化关键点」）。自动路线主路径用 setup_apig_apis.py，setup_vpc_and_triggers.py 作为备选。
2. 为函数配置 5 个环境变量（DB_HOST/DB_PORT/DB_USER/DB_PASSWORD/DB_NAME）并绑定数据库所在 VPC。
3. 创建 APIG 触发器并按「路径 + 方法」发布到 RELEASE。
4. 调用 db-init 完成建表与种子数据。

完成标志：13 个接口调用全部返回 code:0，数据库存在 5 张表。

如果失败：中文乱码、APIG.0101、FSS.1020 等最常见问题见 SKILL 的「全量故障速查表」。

步骤 4：配置、编译并安装端侧

目标：把 APIG 调试域名填入端侧，编译并安装 HAP。

为什么这样做：端侧通过 BASE_URL 指向云侧入口；SDK 版本、工具链路径等环境问题会阻塞编译。

操作：

1. 在 Config.ets 填入 BASE_URL（只填域名，不含函数路径）。
2. 核对 SDK 版本、local.properties 与 DEVECO_SDK_HOME。
3. 执行 ohpm install + hvigorw assembleHap 编译，再用 hdc install 安装。

完成标志：App 图标出现，能启动到登录页。

如果失败：00303217（缺 SDK 环境变量）、00308018 EPERM（路径被改写）、路径含空格等问题见 SKILL 的「端侧编译注意」。

步骤 5：端云联调验收

目标：端到端走通核心业务，确认中英文数据正确。

为什么这样做：这是验证「命令提交成功 ≠ 部署完成」的关键一步，只有实际调用通过才算完成。

操作：按第 5 章的业务验收表逐项执行。

完成标志：第 5 章验收项全部通过，中文留言 / 论坛 / 帖子无乱码。

5. 验收与排障

业务验收

#	操作	预期结果	证据/检查方式
1	用 admin@example.com / 654321 登录	进入留言墙（管理员可见管理入口）	端侧页面截图
2	新用户注册（邮箱 + 6 位以上密码）	提示「注册成功」，可登录	接口返回 code:0
3	发布中文留言	「留言成功」，列表显示正确中文	列表无 � 乱码
4	创建中文论坛并发帖	「论坛创建成功」，内容中文正确	列表展示正确
5	关键字搜索论坛 / 历史发言	返回匹配结果	搜索结果截图
6	管理员删除 / 恢复留言、封禁 / 解封	状态正确变化，被封用户登录被拒	接口响应 + 端侧提示

技术检查与验收环境

• 端侧可编译、安装和启动。
• 云侧 13 个接口调用全部返回 {"code":0,"data":{...}}。
• 核心数据可写入、读取并在端侧正确展示（中文无乱码）。
• 错误场景反馈清楚，日志中无真实凭据或未处理异常。

项目	内容
验证日期	2026-08-14
分支/标签/提交	main
设备与系统	mobile / HarmonyOS 6.1.0
云区域与关键版本	FunctionGraph Node.js 18.15 / APIG 专享版 / RDS MySQL
验收结论	已验收

高频问题

现象/错误码	环节	常见原因	处理与恢复标志
中文变 � 或 ä½ å¥½	云函数	字符集配置错误或 APIG GBK 转换	检查 charset 与 iconv-lite 回退，见 SKILL
APIG.0101	网关	未发布 / 方法路径不符	发布 RELEASE 并核对 GET/POST
FSS.1020	部署	VPC 委托用错字段	用 xrole（VPC FullAccess）
00303217 / 00308018	编译	缺 SDK 环境变量 / 路径被改写	补 DEVECO_SDK_HOME / 修正 sdk.dir

排查顺序：环境与版本 → 配置与权限 → 网络与资源状态 → 云侧日志 → 接口响应 → 端侧日志。

完整故障库：SKILL.md 的「全量故障速查表」。

6. 安全与清理

实验配置与生产要求

项目	本案例演示配置	生产要求
API 认证	NONE（匿名）	正式鉴权、限流、审计
网络	APIG 调试域名	HTTPS、自有域名、证书
凭据	环境变量明文（联调）	密钥管理、最小权限、轮换
数据	演示数据 + 种子账号	隐私、备份、保留与删除策略

清理资源

清理会删除实验资源和数据。先核对资源名称、区域、项目和依赖关系，并导出需要保留的数据。

1. 禁用或删除 db-init 函数的 APIG 触发器。
2. 删除 13 个云函数。
3. 删除 APIG 实例并释放弹性 IP。
4. 删除 RDS 实例。
5. 撤销临时 AK/SK 权限，删除本地 .env 和脱敏前日志。

完成标志：计费控制台中不再存在本案例的持续计费资源，临时凭据已撤销。

7. 项目导览与进阶

关键目录

treehole/
├── README.md                  # 案例入口与学习主线
├── SKILL.md                   # 可复用技巧、代码模板与排障知识
├── harmony_app/               # HarmonyOS 端侧工程
└── harmony_cloud/             # 云侧工程
    ├── database/              # 建表 DDL（4 张表）与种子数据；user_tokens 表由 db-init 创建
    ├── deploy/                # 自动部署脚本与 .env 模板
    └── functions/             # 13 个业务云函数 + echo（调试回显）+ shared（共享 DB 模块）

完成回顾

完成本案例后，你已经：

• 掌握 ArkTS 端侧开发与端云联调的完整流程。
• 掌握 FunctionGraph 云函数编写规范（含中文编码处理、连接池、密码哈希）。
• 掌握 APIG 网关与触发器配置、RDS MySQL 表设计与初始化。
• 交付一个可运行的匿名留言墙 + 论坛 + 管理员后台应用。

深入阅读与扩展

• SKILL.md —— 云函数规范、代码模板、全量排障与复用清单
• 扩展方向：为 APIG 接入正式鉴权、把数据库凭据迁移到密钥管理、为 db-init 增加幂等保护。

8. 参考与维护

官方资料与帮助

• 华为云 FunctionGraph 文档
• 华为云 APIG 文档
• 华为云 RDS for MySQL 文档
• HarmonyOS 开发文档

维护与版本

项目	内容
维护团队	鸿蒙实践案例开发团队
当前案例版本	v1.0.0
最后验证日期	2026-08-14
兼容范围	FunctionGraph Node.js 18.15 / APIG 专享版 / RDS MySQL

许可证

本案例采用 MIT License。第三方依赖及素材遵循各自许可证。