HeliaShare 部署与运维实践
本文分享 HeliaShare 的部署方案和运维经验。
部署方案对比
方案 1: GitHub Pages（推荐）
优点:
- 完全免费
- 自动 HTTPS
- 与代码仓库集成
- 全球 CDN 加速
部署步骤:
# 1. 创建 GitHub 仓库
git init
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/username/heliashare.git
git push -u origin main
# 2. 在仓库设置中启用 Pages
# Settings -> Pages -> Source -> Deploy from a branch
注意: GitHub Pages 不支持自定义响应头，但 HeliaShare 不需要特殊配置。
方案 2: Netlify
优点:
部署步骤:
- 连接 GitHub 仓库
- 自动识别为静态站点
- 自定义域名（可选）
方案 3: 自有服务器 (Nginx)
Nginx 配置:
server {
listen 443 ssl http2;
server_name ipfs.example.com;
root /var/www/heliashare;
index index.html;
# SSL 证书
ssl_certificate /path/to/cert.pem;
ssl_certificate_key /path/to/key.pem;
# 安全头
add_header X-Frame-Options "SAMEORIGIN" always;
add_header X-Content-Type-Options "nosniff" always;
# 缓存静态资源
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
expires 1M;
add_header Cache-Control "public, immutable";
}
# CORS（用于 ES Modules）
location / {
try_files $uri $uri/ =404;
add_header Access-Control-Allow-Origin "*";
}
}
HTTPS 配置要点
为什么必须 HTTPS？
WebRTC 协议要求必须在安全上下文中运行，这是浏览器的安全策略。
错误示例:
http://localhost:8080 ❌ 可能失败（取决于浏览器）
http://192.168.1.100 ❌ 一定失败
https://example.com ✅ 正常工作
本地开发解决方案
方式 1: localhost
# localhost 被视为安全上下文
python3 -m http.server 8080
# 访问 http://localhost:8080
方式 2: mkcert（推荐）
# 安装 mkcert
brew install mkcert # macOS
# 或
choco install mkcert # Windows
# 生成本地证书
mkcert -install
mkcert localhost 127.0.0.1 ::1
# 使用证书启动服务器
npx serve -s . --ssl-cert localhost+2.pem --ssl-key localhost+2-key.pem
方式 3: ngrok
ngrok http 8080
# 获得 https://xxx.ngrok.io 地址
性能优化
资源加载优化
1. CDN 加载 Helia
// 使用 esm.sh CDN
import { createHelia } from 'https://esm.sh/helia@^4.0.0'
// 优点：自动缓存、全球加速、版本管理
2. 预加载关键资源
<link rel="preconnect" href="https://esm.sh">
<link rel="dns-prefetch" href="https://esm.sh">
3. 代码分割（可选）
// 动态导入非关键模块
const { unixfs } = await import('https://esm.sh/@helia/unixfs')
运行时优化
1. 节点初始化优化
// 延迟初始化，等用户交互后再启动
let helia = null
async function getHelia() {
if (!helia) {
helia = await createHelia()
}
return helia
}
2. 连接池管理
// 限制并发连接数
const MAX_CONNECTIONS = 10
if (helia.libp2p.getPeers().length > MAX_CONNECTIONS) {
// 断开多余连接
}
监控与调试
浏览器控制台调试
查看连接节点:
// 在控制台运行
helia.libp2p.getPeers().forEach(p => console.log(p.toString()))
查看存储块:
let count = 0
for await (const _ of helia.blockstore.getAll()) {
count++
}
console.log('存储块数:', count)
添加日志记录
// 关键操作添加日志
const DEBUG = true
function log(...args) {
if (DEBUG) {
console.log('[HeliaShare]', ...args)
}
}
log('节点初始化完成', peerId)
log('文件上传成功', cid.toString())
常见问题排查
问题 1: 节点无法连接
症状: 状态一直显示"正在连接节点"
排查步骤:
- 检查网络连接
- 确认使用 HTTPS
- 查看浏览器控制台错误
- 检查防火墙是否阻止 WebRTC
解决方案:
// 增加连接超时处理
const initTimeout = setTimeout(() => {
showError('节点连接超时，请检查网络')
}, 30000)
helia = await createHelia()
clearTimeout(initTimeout)
问题 2: 文件获取失败
症状: 获取文件时超时或报错
排查步骤:
- 确认 CID 正确
- 检查默认引导节点是否在线
- 查看是否有其他节点提供该内容
解决方案:
// 添加重试机制
async function fetchWithRetry(cid, maxRetries = 3) {
for (let i = 0; i < maxRetries; i++) {
try {
return await fetchFile(cid)
} catch (error) {
if (i === maxRetries - 1) throw error
await sleep(1000 * (i + 1)) // 指数退避
}
}
}
问题 3: 存储空间不足
症状: 上传大文件时浏览器崩溃
解决方案:
// 检查存储空间
if (navigator.storage && navigator.storage.estimate) {
const estimate = await navigator.storage.estimate()
const available = estimate.quota - estimate.usage
if (file.size > available * 0.8) {
showError('存储空间不足')
return
}
}
安全考虑
内容安全策略 (CSP)
<meta http-equiv="Content-Security-Policy" content="
default-src 'self';
script-src 'self' 'unsafe-inline' https://esm.sh;
connect-src 'self' wss: https:;
img-src 'self' blob:;
media-src 'self' blob:;
">
输入验证
// 验证 CID 格式
function isValidCID(cidString) {
try {
CID.parse(cidString)
return true
} catch {
return false
}
}
下一篇预告
最后一篇将分享开发过程中的心得体会，包括：
- 去中心化应用的设计哲学
- IPFS 生态的现状与未来
- 对 Web3 开发者的建议
你在部署过程中遇到过什么问题？欢迎分享经验。