从零到公网可达：用 CodeArts 开发 Flask 服务并用 DevBridge 一键分享

本文记录了一次完整的开发实践：在华为云开发者空间中，用 CodeArts 编写一个 Flask Web 服务，遇到 Python 环境污染问题并修复，最后通过 DevBridge 开发隧道将本地服务暴露到公网，生成可分享的访问链接。全程不到 10 分钟。

## 一、背景：为什么需要 DevBridge？

开发 Web 服务时，一个反复出现的痛点是：**本地跑起来了，但别人访问不了**。

你在自己的开发环境里启动了一个 Flask 应用，`curl localhost:8080` 返回正常，但当你想把 demo 发给同事看看、或者让测试同学调一下接口时，就卡住了——你的机器没有公网 IP，防火墙挡着，VPN 又不通。

传统解法无非这么几种：

| 方案 | 问题 |
|------|------|
| 部署到测试服务器 | 太重了，改一行代码就要重新部署 |
| 用 ngrok / frp 等内网穿透 | 需要自己搭服务或买付费版 |
| 截图发过去 | 不是活的，对方没法交互 |

DevBridge 解决的就是这个问题：**一条命令，把本地端口变成公网可访问的 URL**，用完即走，不碰防火墙，不改网络配置。

## 二、开发：用 CodeArts 写 Flask 服务

### 2.1 创建项目

在华为云开发者空间中，CodeArts 沙箱已经预装就绪。我们通过 ACP（Agent Communication Protocol）与 CodeArts 交互，让它帮我们创建项目结构：

```
python-web-service/
├── app.py              # Flask 主应用
└── requirements.txt    # 依赖声明
```

### 2.2 服务设计

我们要做一个轻量的 Web 服务，包含一个可视化首页和三个 JSON API：

| 端点 | 方法 | 功能 |
|------|------|------|
| `/` | GET | 欢迎页面，渐变背景 + 卡片布局 |
| `/api/health` | GET | 健康检查（状态、时间戳、运行时长） |
| `/api/info` | GET | 服务信息（名称、版本、作者、描述） |
| `/api/time` | GET | 服务器当前时间 |

核心代码如下：

```python
from flask import Flask, jsonify, render_template_string
from datetime import datetime
import time

app = Flask(__name__)
start_time = time.time()

@app.route('/')
def index():
    # 渐变背景 + 卡片布局的欢迎页
    return render_template_string(WELCOME_HTML,
        current_time=datetime.now().strftime('%Y-%m-%d %H:%M:%S'))

@app.route('/api/health')
def health():
    return jsonify(
        status='ok',
        timestamp=datetime.now().isoformat(),
        uptime=round(time.time() - start_time, 2)
    )

@app.route('/api/info')
def info():
    return jsonify(
        name='Python Web Service',
        version='1.0.0',
        author='CodeArts',
        description='A lightweight Flask-based web service.'
    )

@app.route('/api/time')
def get_time():
    return jsonify(
        current_time=datetime.now().strftime('%Y-%m-%d %H:%M:%S'),
        timestamp=datetime.now().isoformat(),
        timezone='CST'
    )

@app.errorhandler(404)
def not_found(e):
    return jsonify(error='Not Found', status=404), 404

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=8080)
```

### 2.3 踩坑：Python 环境污染

代码写完后，安装依赖时遇到了一个经典问题：

```
AssertionError: SRE module mismatch
```

排查发现，沙箱中 `PYTHONPATH` 和 `PYTHONHOME` 环境变量被指向了 CodeArts 自带的 Python 3.12 路径，导致系统 Python 3.11 的模块加载混乱：

```bash
$ echo "PYTHONPATH=$PYTHONPATH"
PYTHONPATH=/root/runtime/codearts/python3.12/lib/python3.12
$ echo "PYTHONHOME=$PYTHONHOME"
PYTHONHOME=/root/runtime/codearts/python3.12
```

**解法**：启动时清除这两个环境变量，用干净的系统 Python 运行：

```bash
env -u PYTHONPATH -u PYTHONHOME /usr/bin/python -m pip install flask==3.0.3
nohup env -u PYTHONPATH -u PYTHONHOME /usr/bin/python app.py &
```

服务顺利启动，所有端点验证通过：

```bash
$ curl -s http://127.0.0.1:8080/api/health
{"status":"ok","timestamp":"2026-11-05T00:06:22.570685","uptime":1.57}

$ curl -s http://127.0.0.1:8080/api/info
{"name":"Python Web Service","version":"1.0.0","author":"CodeArts",...}
```

> **教训**：在沙箱环境中，系统级环境变量可能被运行时污染。遇到 "module mismatch" 类错误，第一时间检查 `PYTHONPATH` / `PYTHONHOME`，用 `env -u` 清除后重试。

## 三、分享：用 DevBridge 暴露到公网

服务在本地跑起来了，但只有同一个开发环境内才能访问。接下来用 DevBridge 把它分享出去。

### 3.1 工作原理

DevBridge 的架构很简洁：

```
你的本地服务 (localhost:8080)
        │
        ▼
DevBridge 沙箱 (WebUI :13000)
        │  出向连接（不需要入向端口）
        ▼
华为云中继服务
        │
        ▼
公网 URL: https://<tunnelId>-<port>.devbridge-s2.hwtunnel.com
```

关键点：DevBridge 通过**出向连接**与华为云中继服务通信，不需要在本地开放任何入向端口。这对防火墙友好的企业内网环境特别实用。

### 3.2 创建隧道

通过 DevBridge WebUI REST API，三步完成：

**第一步：创建隧道**

```bash
# 调用 DevBridge WebUI API
curl -X POST http://localhost:13000/api/tunnels \
  -H 'Content-Type: application/json' \
  -d '{"name":"python-web-tunnel","description":"PythonWeb服务分享","expiration":72}'
```

返回隧道 ID：`g2bqvm5z`

**第二步：配置端口**

```bash
curl -X POST http://localhost:13000/api/tunnels/g2bqvm5z/ports \
  -H 'Content-Type: application/json' \
  -d '{"port":8080,"protocol":"auto","allowAnonymous":true}'
```

- `protocol: auto` — 自动检测 HTTP/HTTPS
- `allowAnonymous: true` — 允许匿名访问，任何人拿到链接就能打开

**第三步：启动托管**

```bash
curl -X POST http://localhost:13000/api/host \
  -H 'Content-Type: application/json' \
  -d '{"tunnelId":"g2bqvm5z"}'
```

### 3.3 获取公网链接

启动托管后，从进程日志中读取隧道 URL：

```bash
$ curl -s http://localhost:13000/api/processes
[{
  "id": "host-1793808490418-87wfir",
  "type": "host",
  "tunnelId": "g2bqvm5z",
  "status": "running",
  "tunnelUrls": ["https://g2bqvm5z-8080.devbridge-s2.hwtunnel.com"]
}]
```

公网链接：

> 🔗 **https://g2bqvm5z-8080.devbridge-s2.hwtunnel.com**

把这个链接发给任何人，他们用浏览器打开就能看到你的欢迎页，访问 `/api/health` 就能调你的接口。不需要登录，不需要 VPN，不需要对方装任何东西。

## 四、效果验证

用外部设备访问公网链接，各端点响应正常：

| 端点 | 状态 | 返回 |
|------|------|------|
| `/` | 200 | 渐变背景欢迎页 |
| `/api/health` | 200 | `{"status":"ok","uptime":52.94}` |
| `/api/info` | 200 | `{"name":"Python Web Service","version":"1.0.0"}` |
| `/api/time` | 200 | `{"current_time":"2026-11-05 00:06:31"}` |
| `/nonexistent` | 404 | `{"error":"Not Found","status":404}` |

## 五、小结

### 我们做了什么

1. **写代码** — 通过 CodeArts ACP 协议，在沙箱中创建 Flask 项目，4 个端点 + 错误处理
2. **修环境** — 排查并修复 Python 环境变量污染问题（`PYTHONPATH` / `PYTHONHOME`）
3. **起服务** — 后台启动 Flask，监听 `0.0.0.0:8080`
4. **开隧道** — DevBridge 创建隧道、配置端口、启动托管
5. **拿链接** — 获取公网 URL，分享给外部用户

### 几个实践建议

- **端口检查不可省**：启动服务前务必 `ss -tlnp | grep :8080` 确认端口空闲，避免冲突
- **环境隔离意识**：沙箱中的环境变量可能被运行时污染，遇到模块加载错误先查 `PYTHONPATH` / `PYTHONHOME`
- **匿名访问按需开启**：`allowAnonymous: true` 方便分享，但意味着任何人拿到链接都能访问，敏感服务慎用
- **隧道用完即删**：DevBridge 隧道默认 72 小时过期，不用时主动删除释放配额
- **域名不要硬编码**：中继域名随集群变化，始终从 API 返回的 `tunnelUrls` 中读取，不要手动拼接

### DevBridge 适用场景

- ✅ 给同事/客户演示本地开发中的 demo
- ✅ 移动端调试本地 API
- ✅ 接收 Webhook 回调（如 GitHub Webhook、支付回调）
- ✅ 临时分享一个本地静态站点
- ❌ 生产环境对外服务（这是开发工具，不是生产网关）

---