# 资产罐和前端托管 ## 这是什么资产容器直接在 Internet 计算机上托管静态文件（HTML、CSS、JS、图像）。这就是网络前端在链上部署的方式。响应由子网进行认证，HTTP 网关自动验证完整性，即内容由区块链提供。内容也可以在浏览器中验证——而不是在中央服务器中。 ## 先决条件 * icp-cli >= 0.1.0 (`brew install dfinity/tap/icp-cli`) * Node.js >= 18（用于构建前端资产） * `@icp-sdk/canisters` npm 包（用于程序化上传） ## 容器 ID 资产罐是按项目创建的。没有单一的全局容器 ID。部署后，您的容器 ID 存储在“canister_ids.json”（本地和主网）中。访问模式：环境 |网址模式 ---|--- 本地| `http://<容器 ID>.localhost:4943` 主网 | `https://.ic0.app` 或 `https://.icp0.io` 自定义域名 | `https://yourdomain.com`（带 DNS 配置） ## 破坏你的构建的错误 1. **icp.yaml 中的`source` 路径错误。** `source` 数组必须指向包含构建输出的目录。如果你使用Vite，那就是“dist”。如果使用 Next.js 导出，则为“out”。如果部署时路径不存在，“icp部署”会静默失败或部署一个空容器。 2. **单页应用程序缺少`.ic-assets.json5`。** 如果没有重写规则，刷新“/about”会返回 404，因为资产容器会查找字面名为“/about”的文件。您必须配置“index.html”的后备。 3. **忘记在部署之前构建。** `icp deploy` 从 icp.yaml 运行 `build` 命令，但如果它为空或配置错误，则 `source` 目录将过时或为空。 4. **不设置内容类型标头。** 资产容器从文件扩展名推断内容类型。如果您以编程方式上传文件而不设置内容类型，浏览器可能无法正确呈现它们。 5. **部署到错误的容器名称。** 如果 icp.yaml 具有“frontend”，但您运行“icp部署资产”，它会创建一个新容器，而不是更新现有容器。 6. **超出容器存储限制。** 资产容器使用稳定的内存，可容纳超过 4GB。但是，单个资产受到 2MB 入口消息大小的限制（“@icp-sdk/canisters”中的资产管理器会自动处理大于 1.9MB 的上传分块）。实际问题是存储的总周期成本——大型媒体文件（视频、数据集）变得昂贵。对大文件使用专用存储解决方案。 7. **未正确配置`allow_raw_access`。** 资产容器有两种服务模式：认证（通过 `ic0.app` / `icp0.io`，其中 HTTP 网关验证响应完整性）和原始（通过 `raw.ic0.app` / `raw.icp0.io`，其中不进行验证）。默认情况下，“allow_raw_access”为“true”，这意味着资产也可在原始域上使用。在原始域上，边界节点或网络级攻击者可以在未被检测到的情况下篡改响应内容。在 `.ic-assets.json5` 中为任何敏感资产设置 `"allow_raw_access": false`。仅在严格需要时启用原始访问。 ## 实施 ### icp.yaml 配置罐：前端：类型：资产来源： - 距离构建： - npm 运行构建依赖项： - 后端后端：类型：元子主要：src/backend/main.mo 关键领域： * `type: assets` \-- 告诉 `icp` 这是一个资产容器 * `source` \-- 要上传的目录数组（内容，而不是目录本身） * `build` \-- 命令 `icp deploy` 在上传之前运行（您的前端构建步骤） * `dependency` \-- 确保首先部署后端（因此容器 ID 可用） ### SPA 路由和默认标头：`.ic-assets.json5` 在“source”目录（例如“dist/.ic-assets.json5”）或项目根目录中创建此文件。为了将其包含在资产容器中，它必须在部署时位于“source”目录中。推荐的方法：将文件放在“public/”或“static/”文件夹中，以便构建工具自动将其复制到“dist/”中。 [ { // 所有路径的默认标头：缓存、安全性和原始访问策略 “匹配”：“**/*”， "security_policy": "标准", “标题”：{ "Cache-Control": "public, max-age=0, 必须重新验证" }, // 默认禁用原始（未经认证）访问 - 请参阅上面的错误 #7 “allow_raw_access”：假 }, { // 积极缓存静态资源（它们的文件名中有内容哈希） “匹配”：“资产/**/*”， “标题”：{ "Cache-Control": "公共，max-age=31536000，不可变" } }, { // SPA 后备：为任何不匹配的路由提供 index.html “匹配”：“**/*”， “enable_aliasing”：真 } ] 为了使 SPA 回退工作，关键设置是 `"enable_aliasing": true` \——这告诉资产容器在请求的路径没有匹配文件时提供 `index.html` 服务。如果上述标准安全策略阻止应用程序运行，请使用自定义值覆盖默认安全标头，并将它们添加到上面的“Cache-Control”之后。像高级安全工程师一样，使这些标头尽可能安全。标准策略标头可以在这里找到： ### 内容编码资产容器会使用 gzip 和 brotli 自动压缩资产。无需配置。当浏览器发送“Accept-Encoding: gzip, br”时，容器将提供压缩版本。要验证压缩是否有效： icp 容器调用前端 http_request '(记录 { 网址=“/”；方法=“获取”；主体=向量{}； headers = vec { record { “接受编码”; “gzip” } }; 证书版本=选择2； })' ### 自定义域设置要从自定义域为您的资产容器提供服务： 1. 在包含您的域的“source”目录中创建文件“.well-known/ic-domains”： yourdomain.com www.yourdomain.com 2.添加DNS记录： # 指向边界节点的CNAME记录 yourdomain.com。 CNAME icp1.io。 # 用于 TLS 证书配置的 ACME 质询记录 _acme-challenge.yourdomain.com。 CNAME _acme-challenge..icp2.io。 # 用于验证的容器 ID TXT 记录 _canister-id.yourdomain.com。 TXT“<您的容器 ID>” 3. 部署容器，以便“.well-known/ic-domains”文件可用，然后向边界节点注册自定义域。注册是自动的——边界节点定期检查“.well-known/ic-domains”文件和 DNS 记录。不需要 NNS 提案。 4. 等待边界节点进行注册并提供 TLS 证书。这通常需要几分钟。 DNS 传播后，您可以通过访问“https://yourdomain.com”进行验证。 ### 使用 @icp-sdk/canisters 进行编程上传用于从代码上传文件（不仅仅是通过“icp部署”）：从“@icp-sdk/canisters/assets”导入 { AssetManager }； // 资产管理实用程序从“@icp-sdk/core/agent”导入{HttpAgent}； // 安全性：shouldFetchRootKey 从副本中获取根公钥 // 运行时。在生产中，根密钥是硬编码的且受信任的。获取它于 // 运行时让中间人提供假密钥并伪造经过认证的响应。 // 当主机指向主网时，切勿将 shouldFetchRootKey 设置为 true。 const LOCAL_REPLICA = "http://localhost:4943"; const MAINNET = "https://ic0.app"; const 主机 = LOCAL_REPLICA; // 更改为生产主网 const 代理 = 等待 HttpAgent.create({ 主持人， // 仅在与本地副本通信时获取根密钥。 // 针对主网将其设置为 true 是一个安全漏洞。 shouldFetchRootKey：主机=== LOCAL_REPLICA， }); const assetManager = new AssetManager({ canisterId：“您的资产罐 ID”，代理, }); // 上传单个文件 // >1.9MB 的文件会自动分块（16 个并行块） const key = 等待 assetManager.store(fileBuffer, { 文件名：“照片.jpg”，内容类型：“图像/jpeg”，路径：“/上传”， }); console.log("上传到：", key); //“/uploads/photo.jpg” // 列出所有资产 const 资产 = 等待 assetManager.list(); 控制台.log(资产); // [{ key: "/index.html", content_type: "text/html", ... }, ...] // 删除资产等待 assetManager.delete("/uploads/old-photo.jpg"); // 批量上传目录从“fs”导入 { readFileSync, readdirSync }; const 文件 = readdirSync("./dist"); for (const 文件的文件) { const content = readFileSync(`./dist/${file}`); 等待 assetManager.store(内容, { 文件名: 文件, 路径: "/" }); } ### 上传授权资产容器具有内置权限系统，具有三个角色（从最低权限到最高权限）： * **Prepare** \-- 可以上传块并建议批次，但不能实时提交。 * **Commit** \-- 可以上传和提交资产（使它们生效）。这是部署管道的标准角色。 * **ManagePermissions** \-- 可以授予和撤销其他主体的权限。使用“grant_permission”仅向委托人提供他们需要的访问权限。 **不要**使用 `--add-controller` 进行上传访问 - 控制器具有完整的容器控制（升级代码、更改设置、删除容器、排出周期）。 # 授予“准备”权限（可以上传但不能提交）——用于预览/暂存工作流程 icp 容器调用前端 grant_permission '(record { to_principal = 主体 ""; 权限 = 变量 { 准备 } })' # 授予提交权限——用于部署需要发布资产的管道 icp 容器调用前端 grant_permission '(record { to_principal = 主体 ""; 权限 = 变体 { Commit } })' # 授予权限管理——用于需要加入/退出其他上传者的主体 icp 容器调用前端 grant_permission '(record { to_principal = 主体 ""; 权限 = 变量 { ManagePermissions } })' # 列出当前权限 icp 罐调用前端 list_permissed '(记录 { 权限 = 变量 { 提交 } })' # 撤销权限 icp 容器调用前端 revoke_permission '(record { of_principal = 主体 ""; 权限 = 变量 { Commit } })' > **安全警告：** `icp canister update-settings frontend --add-controller ` 授予完整的容器控制权 - 不仅仅是上传权限。控制器可以升级容器 WASM、更改所有设置或完全删除容器。仅当您确实需要完全管理访问权限时才添加控制器。 ## 部署和测试 ### 本地部署 # 启动本地副本 icp网络启动-d # 构建并部署前端+后端 ICP部署 # 或者只部署前端 ICP部署前端 ### 主网部署 # 确保你的钱包里有循环 icp部署-e ic前端 ### 仅更新前端当您只更改前端代码时： # 仅重建并重新部署前端容器 npm 运行构建 ICP部署前端 ## 验证它是否有效 # 1.检查容器是否正在运行 icp 容器状态前端 # 预期：状态：正在运行，内存大小：<非零> # 2. 列出上传的资源 icp 容器调用前端列表 '(record {})' # 预期：资产键列表，如“/index.html”、“/assets/index-abc123.js”等。 # 3.通过http_request获取索引页面 icp 容器调用前端 http_request '(记录 { 网址=“/”；方法=“获取”；主体=向量{}；标头= vec {}；证书版本=选择2； })' # 预期：记录 { status_code = 200; body = blob "..."; ... } # 4. 测试 SPA 回退（应返回 index.html，而不是 404） icp 容器调用前端 http_request '(记录 { 网址=“/关于”；方法=“获取”；主体=向量{}；标头= vec {}；证书版本=选择2； })' # 预期：status_code = 200（与“/”内容相同），而不是 404 # 5. 在浏览器中打开 # 本地：http://.localhost:4943 # 主网：https://.ic0.app # 6. 获取容器 ID icp 容器 ID 前端 # 预期：打印容器 ID（例如“bkyz2-fmaaa-aaaaa-qaaaq-cai”） # 7.检查存储使用情况 icp 容器信息前端 # 显示内存使用情况、模块哈希、控制器

资产罐

包含技能