ftp-srv

项目背景与战略目标

ftp-srv 是一个面向 OpenHarmony 平台的 FTP 服务器库，支持文件上传、下载、目录管理等核心功能。在仓颉后端生态中，此类协议级服务组件是构建边缘存储网关、设备本地文件共享服务、自动化测试桩等场景的关键基础设施。本项目将基于仓颉语言 1.0.0+ 的核心优势——编译期内存安全（彻底杜绝缓冲区溢出、Use-After-Free 等 CVE 类漏洞）、轻量级并发模型（通过 async/await 实现万级连接处理）、强类型系统与代数数据类型（精准建模 FTP 命令与状态机），打造一个高并发、高可靠、内存安全的原生 FTP 服务器库。该库将全面支持主动/被动模式、匿名/认证登录、命令黑白名单、事件钩子等企业级特性，并为仓颉生态提供标准化的文件服务能力。

核心功能需求与技术规格

2.1 功能模块分解

2.2 非功能性需求规范

• 性能指标：

  • P99 命令响应延迟 < 5ms（局域网）

  • 单节点吞吐 ≥ 5K 并发连接

  • 内存占用 ≤ 15 MB（空闲服务器实例）

• 安全要求：

  • 所有用户输入经沙箱路径校验，杜绝路径遍历（CVE-2023-1234 类漏洞）

  • 匿名用户根目录强制隔离，禁止向上跳转

  • 100% 通过仓颉编译器内存安全检查

• 可靠性：

  • 网络异常自动清理残留连接

  • 资源（socket、buffer、临时文件）100% RAII 管理

  • 完善的错误日志与上下文追踪

• 可维护性：

  • 命令处理器通过注册表动态加载

  • 接口设计符合仓颉惯用法（如 impl Display for FtpResponse）

  • 代码 100% 通过 cjfmt 格式化

2.3 核心接口设计示例 (伪代码)

// FTP 服务器配置
struct FtpServerConfig {
    bindAddr: String,      // "0.0.0.0:21"
    pasvUrl: String,       // 被动模式返回的 IP
    pasvMin: U16,          // 8881
    pasvMax: U16,          // 8890
    anonymous: Bool,
    blacklist: [String],   // 禁用命令列表
}

// 用户登录上下文
struct LoginContext {
    username: String,
    password: String,
    remoteIp: String,
}

// 服务器错误类型
enum FtpServerError {
    BindFailed(IoError),
    AuthRejected(String),
    FileSystemError(FsError),
}

// 核心服务器接口
interface FtpServer {
    // 注册登录事件（异步鉴权）
    fn onLogin(handler: FnMut(LoginContext, ResolveFn, RejectFn))
    
    // 注册客户端断开事件
    fn onDisconnect(handler: FnMut(ConnectionInfo))
    
    // 启动监听
    async fn listen(config: FtpServerConfig) -> Result<Void, FtpServerError>
    
    // 停止服务
    fn quit() -> Result<Void, FtpServerError>
}

// 回调类型别名
type ResolveFn = FnOnce(UserRoot);
type RejectFn = FnOnce(String); // 错误消息
struct UserRoot {
    rootPath: String, // 用户可见的根目录
}

项目交付物与实施路线图

3.1 阶段性交付物清单

• 第一阶段：FTP 核心命令实现（USER/PASS/CWD/STOR/RETR/LIST） + 控制/数据连接管理 + 单元测试（覆盖率≥95%） + 接口文档

• 第二阶段：被动模式调度 + 事件钩子系统 + 高并发压力测试（10K 连接） + 与 FileZilla/WinSCP 兼容性验证

• 第三阶段：安全加固报告 + cjpm 发布包 + 生产部署指南（含 Docker 示例）

3.2 项目实施路线图

技术实现规范与质量认证体系

4.1 仓颉语言专项质量规范

• 编码规范：100% 通过 cjfmt --check，禁止使用 unsafe 块

• 类型安全：

  • FTP 响应码封装为 FtpResponseCode 枚举

  • 用户路径使用 VirtualPath 新类型，防止 ../ 遍历

• 错误处理：所有 public API 返回 Result<T, FtpServerError>，禁止隐式 panic

4.2 测试与验证标准

• 单元测试：核心模块行覆盖率 ≥ 95%（cjpm test --coverage 验证）

• 性能基准：

  • 建立 benches/ftp_srv_bench.cj 对比 Node.js ftp-srv

  • 监控 STOR 和 RETR 的内存分配次数

• 安全扫描：集成 cj-analyzer 检测路径遍历、未授权访问等风险

4.3 文档与可维护性

• API 文档：所有 public 接口包含 /// 注释，说明线程安全性和资源释放要求

• 架构决策记录：

  • ADR-01：为何采用事件驱动而非中间件链

  • ADR-02：PASV 端口分配的安全策略

• 贡献指南：明确 PR 需包含：协议兼容性说明 + 基准测试对比

4.4 持续集成质量门禁

# PR 自动化流水线
cjpm fmt --check
cjpm build --release
cjpm lint --deny-warnings
cjpm test --all-features --coverage
cjpm bench --baseline=main

技术栈与开发环境

• 核心语言：仓颉编程语言（Cangjie Language）1.0.0+

• 构建工具：CJPM (Cangjie Package Manager)

• 测试框架：@std/testing 原生测试库

• 质量工具：cjfmt, cjpm lint, cjpm bench

• 开发环境：

  • 本地：仓颉 1.0.0+ SDK（Linux/macOS）

  • CI：cangjie-lang/cjci:1.0.0 官方 Docker 镜像

交付件

验收标准

1.功能

1. 三方库必须有明确的功能；

2. 如果参考对标库移值开发，功能与参考三方库保持一致。

2.资料

1. Readme：包含简介，软件架构，目录结构，下载安装（编译构建），接口说明，使用示例，约束限制，开源协议，参与贡献等内容；

2. Changelog，三方库版本需包含基本的修改说明。

3.标准遵从性（可选），三方库实现需满足对应协议或行业标准，举例

1. appquth：支持对OAuth 的PKCE扩展；

2. icu4j：支持unicode标准库，通用字符集ISO/IEC 10646。

4.性能目标

1. 性能敏感三方库接口运行性能持平对标三方库

5.开源协议遵从，必须包含License文件

1. 放置合适的开源License协议，建议Apache License Version 2.0；

2. 引用或参考开源三方库，需遵从开源协议。

6.网络安全要求

1. 满足基础的网络安全红线及隐私要求，符合安全编码规范。

过程质量要求