{"id":15456006,"url":"https://github.com/daijiale/ipfs-geo","last_synced_at":"2025-04-21T15:40:10.320Z","repository":{"id":86417208,"uuid":"123525741","full_name":"daijiale/ipfs-geo","owner":"daijiale","description":"a geography relation object model demo with ipfs","archived":false,"fork":false,"pushed_at":"2018-05-26T09:23:07.000Z","size":23,"stargazers_count":23,"open_issues_count":0,"forks_count":6,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-20T00:59:54.531Z","etag":null,"topics":["dapp","geohash","geohash-ipfs","ipfs","ipfs-geo"],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/daijiale.png","metadata":{"files":{"readme":"README-zh.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-03-02T03:31:47.000Z","updated_at":"2024-05-30T10:57:39.000Z","dependencies_parsed_at":"2023-03-13T20:00:06.303Z","dependency_job_id":null,"html_url":"https://github.com/daijiale/ipfs-geo","commit_stats":{"total_commits":6,"total_committers":1,"mean_commits":6.0,"dds":0.0,"last_synced_commit":"484d155c5a2648abb4644d29b761a271c5540244"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daijiale%2Fipfs-geo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daijiale%2Fipfs-geo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daijiale%2Fipfs-geo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daijiale%2Fipfs-geo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/daijiale","download_url":"https://codeload.github.com/daijiale/ipfs-geo/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249834788,"owners_count":21331988,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dapp","geohash","geohash-ipfs","ipfs","ipfs-geo"],"created_at":"2024-10-01T22:21:54.853Z","updated_at":"2025-04-20T01:00:26.005Z","avatar_url":"https://github.com/daijiale.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"![](http://career-pic.oss-cn-beijing.aliyuncs.com/ipfs-smart-object/ipfsgeo/ipfs-geo-dark.jpg)\n\n# [ipfs-geo]\n\n[![jaywcjlove/sb](https://jaywcjlove.github.io/sb/lang/chinese.svg)](README-zh.md)\n\n 这是一个关于`IPFS-GEO`的研究方向项目，维护了一个位置信息与IPFS存储方式的关系对象模型，欢迎免费`star`以及`fork`。\n\n任何评论，建议，都可以[提交issue](https://github.com/daijiale/ipfs-geo/issues)，我们十分期望建设性的PR！\n\n## Explanation\n\n[English](README.md) | [中文](README-zh.md)\n\n## 一、概述\n\n### 1.1 项目意义\n\n打造地理位置信息与区块链的关系对象模型，建立一套 **人-\u003e位置-\u003e真实世界-\u003e传递信任-\u003e价值转移-\u003e位置-\u003e人** 的生态模型，实现用区块链来索引真实世界的愿景。\n\n而GeoHash算法可以大幅度提高在庞大位置数据中的检索效率，同时为应用提供便捷的缓存机制。\n\nIPFS\u0026Filecoin技术则可以保证在一个可信的区块链网络中去大规模传递与海量位置信息相关联的海量文件、数据集合，并保证传递过程中数据的产权价值。\n\n### 1.2 名词解释\n\n#### DDApp\n\nDDApp ( Data Decentered Application )：是一个**数据去中心化应用**的概念，介于传统应用和去中心化应用之间，解决了DApp不能依赖中心化的API的问题，又保证部分需要去中心化场景下的数据，在与应用交互之外，还可以独立分布部署、P2P传输。\n\n#### IPFS\n\nIPFS全称InterPlanetary File System，中文名：星际文件系统，是一个旨在创建持久且分布式存储和共享文件的网络传输协议。它是一种内容可寻址的对等超媒体分发协议可以让网络更快、更安全、更开放。它是一个面向全球的、是一个点对点的分布式版本文件系统，试图将所有具有相同文件系统的计算设备连接在一起。\n\n#### GeoHash\n\nGeohash是由Gustavo Niemeyer发明的公共域地理编码系统，它将一个地理位置编码成一串字母和数字。\n\n它是一种层次化的空间数据结构，将空间细分为网格形状的桶，是一种被称为z -阶空间填充曲线的应用，下图中就是GeoHash算法中常用的Peano曲线，一种四叉树线性编码方式。\n\n![](http://daijiale-cn.oss-cn-hangzhou.aliyuncs.com/djl-blog-pic/geo-search/suanfa-geo-hash.png)\n\nGeoHash数据将具有如下3个特点：\n\n- 1）GeoHash将二维的经纬度转换成字符串，比如下图展示了北京9个区域的GeoHash字符串，分别是WX4ER，WX4G2、WX4G3等等，每一个字符串代表了某一矩形区域。也就是说，这个矩形区域内所有的点（经纬度坐标）都共享相同的GeoHash字符串，这样既可以保护隐私（只表示大概区域位置而不是具体的点），又比较容易做缓存，比如左上角这个区域内的用户不断发送位置信息请求餐馆数据，由于这些用户的GeoHash字符串都是WX4ER，所以可以把WX4ER当作key，把该区域的餐馆信息当作value来进行缓存，而如果不使用GeoHash的话，由于区域内的用户传来的经纬度是各不相同的，很难做缓存。\n\n![](http://daijiale-cn.oss-cn-hangzhou.aliyuncs.com/djl-blog-pic/geo-search/weilan1-geo-hash.png)\n\n- 2）字符串越长，表示的范围越精确。如图所示，5位的编码能表示10平方千米范围的矩形区域，而6位编码能表示更精细的区域（约0.34平方千米）\n\n![](http://daijiale-cn.oss-cn-hangzhou.aliyuncs.com/djl-blog-pic/geo-search/weilan2-geo-hash.png)\n\n- 3）字符串相似的表示距离相近（特殊情况后文阐述），这样可以利用字符串的前缀匹配来查询附近的POI信息。如下两个图所示，一个在城区，一个在郊区，城区的GeoHash字符串之间比较相似，郊区的字符串之间也比较相似，而城区和郊区的GeoHash字符串相似程度要低些。\n\n`例如，坐标对（116.414597,39.955441），位于北京安定门附近，GeoHash后形成的值为WX4G2`\n\n我们已经知道现有的GeoHash算法使用的是Peano空间填充曲线，这种曲线会产生突变，造成了编码虽然相似但距离可能相差很大的问题，因此在基于个人位置查询附近Poi信息时，首先筛选GeoHash编码相似的POI点，然后进行实际距离计算，来规避算法突变所造成的误差。\n\n当然Geohash只是空间索引的一种方式，特别适合POI点数据，而对线Link、面数据采用R树索引更有优势\n\n## 二、系统设计\n\n### 2.1 架构设计\n\n![](http://daijiale-cn.oss-cn-hangzhou.aliyuncs.com/djl-blog-pic/geo-search/IPFS-Geography.png)\n\n### 2.2 对象模型设计\n\n**Geo Object Model**\n\n属性                   | 类型       | 备注\n-------------------- | -------- | --------------\ngeo_id               | INT      | 唯一标识\ngeo_address          | STRING   | 地址名\ngeo_lng              | FLOAT    | 位置经度\ngeo_lat              | FLOAT    | 位置纬度\ngeo_hash             | STRING   | 位置生成的GeoHash值\nipfs_hash            | STRING   | 所存数据的IpfsHash值\naddGeoInfoByParam()  | FUNCTION | 添加位置信息方法\ngetGeoInfoByParam()  | FUNCTION | 获取位置信息方法\nmixGeoHashByParam()  | FUNCTION | GeoHash生成算法\naddIpfsDataByParam() | FUNCTION | 添加Ipfs数据方法\nmixIpfsHashByParam() | FUNCTION | 关联Ipfs数据方法\n\n### 2.3 数据库对象映射\n\n#### 2.3.1 数据库选型\n\n\u003e 这是网友以 100万 poi 数据查询范围 3km 内的点（最多取100条）的性能测试统计\n\n**以下是各数据库的对比情况：**\n\n数据库               | 耗时      | 区域查询 | 多条件支持\n----------------- | ------- | ---- | -----\nredis(3.2.8)      | 1-10ms  | 支持   | 不支持\nmongo(3.4.4)      | 10-50ms | 支持   | 支持\npostgreSQL(9.6.2) | 3-8ms   | 支持   | 支持\nmysql（5.7.18）     | 8-15ms  | 支持   | 支持\n\n**综合比较后，个人选择了MySql 来进行后文Demo的支撑数据库**\n\n- MySql在5.7.4以前版本的童鞋可以通过myISAM引擎提供的Geom内置函数来实现\n- MySql在5.7.4以后版本的童鞋可以舒服的继续使用InnoDB引擎，官方对其添加了对空间索引的支持，感兴趣的朋友也可以对比下性能。\n\n**PS：**\n\n- 1 . 数据库没有哪个一定好，只要适合场景即可。\n- 2 . 在研究IPFS存储性能的过程中，由于测试网络节点问题，有很严重的数据传输瓶颈，且不稳定，短期内，很难将**需要频繁更新**以及**百万级别数据**的检索逻辑事务放在IPFS这一层中来做。\n- 3 . 在IPFS节点网络性能目前并不乐观的情况下，尝试去寻找能实现具有商业级别能力IPFS应用的**过渡方案**\n\n#### 2.3.2 对象模型映射成表结构\n\n```sql\n\n\n-- 表的结构 `geo_object`\n--\n\nCREATE TABLE `geo_object` (\n  `geo_id` bigint(20) NOT NULL  AUTO_INCREMENT,\n  `geo_loc` point NOT NULL,\n  `geo_address` varchar(255) NOT NULL,\n  `ipfs_hash` varchar(255) NOT NULL\n) ENGINE=MyISAM DEFAULT CHARSET=utf8 COMMENT='geo对象模型';\n\n-- Indexes for table `geo_object`\nALTER TABLE `geo_object`\n  ADD PRIMARY KEY (`geo_id`),\n  ADD SPATIAL KEY `geo_loc` (`geo_loc`);\n```\n\n## 三、Demo\n\n有了以上的概念和设计模型，接下来，给大家看一个简单的Demo实现：\n\n### 3.1 通过IPFS上传位置数据\n\n- IPFS单节点的部署就不详细介绍了，这边可以参考文章[【应用】利用IPFS构建自己的去中心化分布式Wiki系统](https://www.daijiale.cn/%E5%8C%BA%E5%9D%97%E9%93%BE/%E3%80%90%E5%8C%BA%E5%9D%97%E9%93%BE%E3%80%91%E5%88%A9%E7%94%A8ipfs%E6%9E%84%E5%BB%BA%E8%87%AA%E5%B7%B1%E7%9A%84%E5%8E%BB%E4%B8%AD%E5%BF%83%E5%8C%96%E5%88%86%E5%B8%83%E5%BC%8Fwiki%E7%B3%BB%E7%BB%9F.html) 的实现过程\n\n- 官方提供了Curl的API方式，我们可以通过`addIpfsDataByParam()`方法实现RPC调用。\n\n  ```\n  curl -F file=@myGeoFile \"http://localhost:5001/api/v0/add?recursive=false\u0026quiet=false\u0026hash=sha2-256\"\n  ```\n\n- **PS：**这边Demo采用的是本地单节点的数据上传，为了保障服务的稳定性，建议使用**ipfs-cluster的节点集群解决方案**，具体方案可以参考**IPFS资深大牛（飞向未来）**的文章[《IPFS家族二》](http://ipfser.org/2018/03/02/r26/)\n\n### 3.2 获取IPFS网络返回值，并关联数据\n\n响应体为 'multipart/form-data'格式，成功，会返回如下Body数据：\n\n```json\n{\n    \"Name\":\"myGeoFile\"\n    \"Hash\":\"QmYftndCvcEiuSZRX7njywX2AGSeHY21Sa7VryCq1mK1Ew\"\n    \"Bytes\":\"2428803\"\n    \"Size\": \"\"\n}\n```\n\n拿到Hash值后，再通过`mixIpfsDataByParam()`方法关联到我们的Geo位置数据上\n\n### 3.3 Geo模型预演\n\n#### 选取第一个基准位置点（模拟用户所在定位）\n\n![Alt text](http://daijiale-cn.oss-cn-hangzhou.aliyuncs.com/djl-blog-pic/geo-search/geo-poi-3w.png)\n\n- 维度lat：39.989049\n- 经度lng：116.313658\n\n```sql\nINSERT INTO `geo_object`(`geo_loc`, `geo_address`, `ipfs_hash`) VALUES (GeomFromText('POINT(39.989049 116.313658)'),'3W咖啡馆','QmYftndCvcEiuSZRX7njywX2A21Sa7VryCq1mK1Ew21')\n```\n\n#### 选取第二个Geo位置点（模拟近点）\n\n![Alt text](http://daijiale-cn.oss-cn-hangzhou.aliyuncs.com/djl-blog-pic/geo-search/geo-poi-zhongguancun.png)\n\n- 维度lat：39.988878\n- 经度lng：116.313352\n\n  ```sql\n  INSERT INTO `geo_object`(`geo_loc`, `geo_address`, `ipfs_hash`) VALUES (GeomFromText('POINT(39.988878 116.313352)'),'中关村创业大街南广场','WCJIEFSCvcE231233HY21Sa7Vr1Cq1mK1Ew')\n  ```\n\n#### 选取第三个Geo位置点（模拟远点）\n\n![](http://daijiale-cn.oss-cn-hangzhou.aliyuncs.com/djl-blog-pic/geo-search/geo-poi-ymy.png)\n\n- 维度lat：40.005466\n- 经度lng：116.315938\n\n```sql\nINSERT INTO `geo_object`(`geo_loc`, `geo_address`, `ipfs_hash`) VALUES (GeomFromText('POINT(40.005466 116.315938)'),'圆明园','KBYftndCvcEiuSZRX7njyw1332Y21Sa723mKASDED')\n```\n\n#### 球面距离围栏算法\n\n假设球面围栏对角点坐标A1（x1，y1），B1（x2，y2）：\n\n```\nx1 = lat + distance / ( 111.1 / COS(RADIANS(lng))),  \ny1 = lng + distance / 111.1  \n\nx1 = lat - distance / ( 111.1 / COS(RADIANS(lng))),  \ny1 = lng - distance / 111.1  \n\n//构建一阶空间填充曲线\nLineString(A1,B1)\n```\n\n**PS：**\n\n- 1.赤道上经度的每个度大约相当于111.1km，经度的每个度的距离从0km到111.1km\n- 2.RADIANS()为弧度计算内置函数\n- 3.LineString() 为构建一阶空间填充曲线内置函数ANA\n\n### 3.4 获取地理区域内的IPFS数据服务\n\n#### 获取1km以内的IPFS数据\n\n```sql\nSELECT  *  \n    FROM    geo_object  \n    WHERE   MBRContains  \n                    (  \n                    LineString  \n                            (  \n                            Point  \n                                    (  \n                                    39.989049 + 1 / ( 111.1 / COS(RADIANS(116.313658))),  \n                                    116.313658 + 1 / 111.1  \n                                    ),  \n                            Point  \n                                    (  \n                                    39.989049 - 1 / ( 111.1 / COS(RADIANS(116.313658))),  \n                                    116.313658 - 1 / 111.1  \n                                    )   \n                            ),  \n                    geo_loc  \n                    )\n```\n\n如下图所示，我们拿到了距离`3W咖啡馆1Km以内中关村大街南广场附近`相关联的IPFS数据 ![](http://daijiale-cn.oss-cn-hangzhou.aliyuncs.com/djl-blog-pic/geo-search/geo-search-1km.png)\n\n#### 获取10km以内的IPFS数据\n\n```sql\nSELECT  *  \n    FROM    geo_object  \n    WHERE   MBRContains  \n                    (  \n                    LineString  \n                            (  \n                            Point  \n                                    (  \n                                    39.989049 + 10 / ( 111.1 / COS(RADIANS(116.313658))),  \n                                    116.313658 + 10 / 111.1  \n                                    ),  \n                            Point  \n                                    (  \n                                    39.989049 - 10 / ( 111.1 / COS(RADIANS(116.313658))),  \n                                    116.313658 - 10 / 111.1  \n                                    )   \n                            ),  \n                    geo_loc  \n                    )\n```\n\n如下图所示，我们拿到了距离`3W咖啡馆10Km以内圆明园附近`相关联的IPFS数据\n\n![](http://daijiale-cn.oss-cn-hangzhou.aliyuncs.com/djl-blog-pic/geo-search/geo-search-10km.png)\n\n**PS：** 关于Demo这块，后续会另外新开一篇实战文章[【应用】基于IPFS和GeoHash构建具有地理位置价值服务的DDApp（实战篇）]()来做专门介绍，让大家也能自己动手编写一个功能相对完善（可视化界面）DDApp 。\n\n## 四、应用场景\n\n- **Vevue：**一个在选定的区域内街拍可获得代币奖励的DApp，鼓励用户分享原创内容，激励场景化广告。\n- **地理位置签到：**只有到达指定位置坐标点，才可取得可信签到密码凭证，进行核对，确认地理位置信任问题。(滴滴加班公司打车报销场景)\n- **到店红包（糖果）：**，吸引用户到达指定实体店铺位置，通过位置可信核对，分发代币糖果凭证/快照，激励用户到店消费，体验现场活动。\n- **车主停车位产权保护：**经过购买的专用停车位实为车主用户的资产，应受到产权保护，且车位的转移、交易需要在一套依赖地理位置的信任体系中进行。\n- **景区、名胜古迹、历史遗迹信息保护：**沧海桑田，地转星移，也许有一天名胜古迹不复存在，但它们的电子信息（地理位置、图像、所属国家、历史文化、视频、VR全景等信息）将永远被保存在区块链上，真实且不被篡改，源远流长。\n- **与位置AR游戏结合：**之前很火的Pokémon Go如果再加上Filecoin的奖励机制会是一种什么样的场面？也可以参考MANA区块链项目的价值。\n- **物联网结合：** 充电桩，ETC这些具有支付属性、位置属性的智能设备创新等等。\n\n## 五、开源计划\n\n**初衷：**期望能让大家看到区块链的实际应用场景，为区块链和传统技术的结合做更多预演、布道、分享，不去听币圈熙熙攘攘的声音，用技术创造真实的价值，也期待更多和我一样想法的朋友加入，带一些正能量给这个圈子。\n\n### IPFS-Geo\n\n**意义：**是一个具有地理位置特征的IPFS智能对象，其元数据具备Geo相关特性，支持**千万级别空间数据**的快速索引，对象内还提供LBS相关功能的接口服务。\n\n![](http://career-pic.oss-cn-beijing.aliyuncs.com/ipfs-smart-object/ipfsgeo/ipfs-geo-dark.jpg)\n\n## 参考文献\n\n- [Wikipedia GeoHash](https://en.wikipedia.org/wiki/Geohash)\n- [黎跃春区块链博客](http://liyuechun.org/2017/11/22/ipfs-api/#35-%E5%AE%89%E8%A3%85`ipfs-api`)\n- [GeoHash核心原理解析](https://www.cnblogs.com/LBSer/p/3310455.html)\n- [【应用】利用IPFS构建自己的去中心化分布式Wiki系统](https://www.daijiale.cn/%E5%8C%BA%E5%9D%97%E9%93%BE/%E3%80%90%E5%8C%BA%E5%9D%97%E9%93%BE%E3%80%91%E5%88%A9%E7%94%A8ipfs%E6%9E%84%E5%BB%BA%E8%87%AA%E5%B7%B1%E7%9A%84%E5%8E%BB%E4%B8%AD%E5%BF%83%E5%8C%96%E5%88%86%E5%B8%83%E5%BC%8Fwiki%E7%B3%BB%E7%BB%9F.html)\n- [Vevue：一个在选定的区域内街拍可获得代币奖励的DApp](http://cn.vevue.com/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaijiale%2Fipfs-geo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdaijiale%2Fipfs-geo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaijiale%2Fipfs-geo/lists"}